minimal-vibe-coding-kit 0.4.2 → 0.5.0

package/CHANGELOG.md

@@ -1,5 +1,35 @@
 # Changelog
 
+## Unreleased
+
+## 0.5.0 — 2026-07-20
+
+### Added
+
+- Added `/claim <request>` across Claude Code, Cursor, Codex, and Grok. It validates official sources, rejects unsafe or misleading URLs, checks new ideas against `backbone.yml` and existing repository conventions, stops for decisions when approval is required, and integrates only the smallest reviewed change with an evidence ledger.
+- Added `/tutien`, a private, user-invoked xianxia coding-classification game built from Git history and explicitly supplied conversation exports. It provides deterministic vi/en reports, ten cultivation realms, evidence-bound workflow coaching, optional aggregate snapshots, progress comparisons, and opt-in antagonists that challenge workflow patterns rather than the person.
+- Added `/tutien classify` with independent Dao faction, affiliation, and technical-path axes; a cultivation-knowledge taxonomy linked to real kit skills; and seven deterministic, token-independent progression metrics.
+- Added complete Simplified Chinese documentation (`docs/README.zh-CN.md`) alongside English and Vietnamese, with synchronized language navigation and npm package inclusion.
+
+### Changed
+
+- Refined `/tutien` with the cross-model namespace `tutien-coding-cultivation-v1`, calm `serene`/`spirited` narration, plain evidence beneath the lore, and reliable English/Vietnamese stop requests that restore the kit's normal writing style. Legacy `gentle`/`spicy` tone values remain compatible.
+- Centralized skill distribution in `.vibekit/skills/skills-manifest.json`, keeping canonical skills, tool mirrors, installer registries, validator registries, package contents, documentation, and per-profile tests synchronized.
+- Strengthened `/claim` with canonical redirect validation, HTTPS-only remote evidence, private-host and confusable-domain rejection, untrusted-content handling, explicit approval states, separate approval for integration-time execution, and a complete distribution checklist.
+- Strengthened `/tutien` with one fail-closed policy state shared by rendering and persistence, idempotent event progression, boundary-aware path matching, metadata-only classification scope, and explicit authorization handling for legitimate dual-use security work.
+
+### Security and privacy
+
+- `/tutien` remains offline and read-only during analysis. Raw prompts, secrets, author names, email addresses, and commit subjects do not enter reports or snapshots; stored history uses salted digests and aggregate evidence.
+- Ambiguous, unauthorized, or declared-stop classifications suppress scores, realms, villains, recommendations, and positive progression. The game evaluates workflow evidence—not a person's identity, worth, health, or wellbeing—and stays isolated from unrelated support or companion modes.
+- `/claim` treats fetched pages as untrusted data and never runs remote installers, lifecycle scripts, or source-provided commands during research.
+
+### Validation
+
+- Expanded `/tutien` coverage to **133 deterministic, offline checks**, including adversarial privacy, token-integrity, policy-state, replay-idempotency, namespace-isolation, natural stop-request, and end-to-end approval-boundary cases.
+- `pack-dry-run.mjs` now parses `npm pack --dry-run --json` and fails with the exact missing path when an on-disk skill file is absent from the package.
+- Synchronized the release version to `0.5.0` in `package.json`, `.codex-plugin/plugin.json`, and both README badges.
+
 ## 0.4.2 — 2026-07-18
 
 - Added a Grok Build (Grok CLI) surface across the kit: `.grok/rules/` (always-on, every `*.md` loaded), `.grok/skills/` (all 13 kit skills, user-invocable as `/<skill-name>`), `.grok/README.md`, and project-scoped `[permission]` deny rules in `.grok/config.toml` mirroring the kit's dangerous-command deny list; `config.example.toml` documents the user-level `~/.grok/config.toml` settings. Added a `grok` install/update profile to `mvck.mjs` (included in `all`) and registered Grok everywhere Claude/Cursor/Codex already were: `validate-kit.mjs`, npm package files, `backbone.yml` `agent_surfaces`, `AGENTS.md`, the AgentShield probe, both READMEs, `INSTALL.md`, `BACKBONE_REFERENCE.md`, `CONTEXT_TEMPLATE.md`, `FIRST_TIME_INIT.md`, and `vibekit-init`.

package/README.md

@@ -1,12 +1,12 @@
 <div align="center">
 
-**Read in:** **English** · [Tiếng Việt](docs/README.vi.md)
+**Read in:** **English** · [Tiếng Việt](docs/README.vi.md) · [简体中文](docs/README.zh-CN.md)
 
 # Minimal Vibe Coding Kit
 
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](LICENSE)
 [![npm](https://img.shields.io/badge/npm-minimal--vibe--coding--kit-cb3837?logo=npm)](https://www.npmjs.com/package/minimal-vibe-coding-kit)
-[![Version](https://img.shields.io/badge/version-0.4.2-2ea44f.svg)](CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-0.5.0-2ea44f.svg)](CHANGELOG.md)
 ![Claude](https://img.shields.io/badge/Claude%20Code-Commands%20%26%20Skills-111111)
 ![Cursor](https://img.shields.io/badge/Cursor-Rules%20%26%20Commands-1f6feb)
 ![Codex](https://img.shields.io/badge/Codex-AGENTS.md%20%26%20Plugin-6f42c1)
@@ -84,12 +84,12 @@ npx mvck install .        # required — copies the kit out of node_modules into
 
 Either way, the short `mvck` command (alias: `vibe-kit`) is then available via `npx`:
 
-| Short command | What it does |
-| --- | --- |
-| `npx mvck install .` | Copy the kit into the repo (`--profile`, `--dry-run`, `--force`) |
-| `npx mvck update .` | Refresh kit-owned files after a new kit release |
-| `npx mvck doctor .` | Read-only health check |
-| `npx mvck validate .` | Structure validation |
+| Short command         | What it does                                                     |
+| --------------------- | ---------------------------------------------------------------- |
+| `npx mvck install .`  | Copy the kit into the repo (`--profile`, `--dry-run`, `--force`) |
+| `npx mvck update .`   | Refresh kit-owned files after a new kit release                  |
+| `npx mvck doctor .`   | Read-only health check                                           |
+| `npx mvck validate .` | Structure validation                                             |
 
 Then continue with **step 2** of the Quick Start (paste the init prompt).
 
@@ -145,42 +145,46 @@ You (prompt) ──▶ Claude Code / Cursor / Codex / Grok
 1. **Just code.** Ask for features and fixes normally; the agent follows `backbone.yml` conventions and keeps diffs small.
 2. **Big or vague task?** Start with the `clearthought` or `sequential-thinking` skill to get a plan first.
 3. **Complex task but only a rough prompt?** `/prompt-sharpener <rough prompt>` sharpens it into a precise prompt and executes it in the same turn.
-4. **Repo-wide question or big review?** Use `parallel-analysis` — it fans out read-only analysis lanes and verifies the merged result.
-5. **Changed `.claude/`, skills, hooks, or installer scripts?** Run `/security-scan` before merging.
-6. **Want measurable improvements?** Run `/autoresearch-coding` with a metric and budget.
-7. **Keep the setup sharp:** `/daily-enhance` proposes improvements — it never applies them silently.
-8. **Onboarding finished for good?** `/vibe-finalize` moves one-time bootstrap files out.
+4. **Found a skill, rule, or tool you want to bring in?** `/claim <request + links>` validates the sources against official docs, checks fit with your repo, asks when unclear, then integrates and documents it.
+5. **Want a quiet reset while reviewing progress?** `/tutien` is a private, wholesome xianxia classification game over Git history + supplied AI-chat exports. It uses a refined mystical voice to reflect on realms, token use, and workflow habits without changing the evidence; `/tutien off` restores the kit's normal writing style.
+6. **Repo-wide question or big review?** Use `parallel-analysis` — it fans out read-only analysis lanes and verifies the merged result.
+7. **Changed `.claude/`, skills, hooks, or installer scripts?** Run `/security-scan` before merging.
+8. **Want measurable improvements?** Run `/autoresearch-coding` with a metric and budget.
+9. **Keep the setup sharp:** `/daily-enhance` proposes improvements — it never applies them silently.
+10. **Onboarding finished for good?** `/vibe-finalize` moves one-time bootstrap files out.
 
 ## Commands
 
-| Command | What it does | Example |
-| --- | --- | --- |
-| `/init-vibe` | First-time init or repair: propose one diff, wait for approval. | `/init-vibe` — then review the diff and answer `yes`. |
-| `/security-scan` | Read-only AgentShield probe + optional scanner over agent surfaces. | `/security-scan` before merging changes to `.claude/**` or skills. |
-| `/daily-enhance` | Propose-only report to improve rules, skills, and workflows. | `/daily-enhance` — review the proposed diff, then approve. |
-| `/autoresearch-coding` | Metric-driven experiment loop with baseline and budget. | `/autoresearch-coding` Goal: fewer lint errors. Budget: 3. |
-| `/council` | Coordinates reviewer/researcher/analyst agents into one merged plan. | `/council` on this branch diff. |
-| `/vibe-finalize` | Graduate the project: move one-time bootstrap files to `_vibekit-cleanup/`. | `/vibe-finalize` — preview first, apply after approval. |
+| Command                | What it does                                                                | Example                                                            |
+| ---------------------- | --------------------------------------------------------------------------- | ------------------------------------------------------------------ |
+| `/init-vibe`           | First-time init or repair: propose one diff, wait for approval.             | `/init-vibe` — then review the diff and answer `yes`.              |
+| `/security-scan`       | Read-only AgentShield probe + optional scanner over agent surfaces.         | `/security-scan` before merging changes to `.claude/**` or skills. |
+| `/daily-enhance`       | Propose-only report to improve rules, skills, and workflows.                | `/daily-enhance` — review the proposed diff, then approve.         |
+| `/autoresearch-coding` | Metric-driven experiment loop with baseline and budget.                     | `/autoresearch-coding` Goal: fewer lint errors. Budget: 3.         |
+| `/council`             | Coordinates reviewer/researcher/analyst agents into one merged plan.        | `/council` on this branch diff.                                    |
+| `/vibe-finalize`       | Graduate the project: move one-time bootstrap files to `_vibekit-cleanup/`. | `/vibe-finalize` — preview first, apply after approval.            |
 
 ## Skills
 
-All 13 skills live in `.vibekit/skills/` and are mirrored for each tool. Invoke them by name ("Use the X skill…") or via the commands above.
-
-| Skill | Use it when | Example prompt |
-| --- | --- | --- |
-| `vibekit-init` | First-time setup, or `backbone.yml` / managed blocks need repair. | "Use the vibekit-init skill. Propose one diff and wait for my yes." |
-| `parallel-analysis` | Repo-wide questions, large diff reviews, consistency audits. | "Use parallel-analysis: where is auth handled and what depends on it?" |
-| `agentshield-security-review` | Auditing agent config, skills, hooks, MCP, commands before merge. | "Use agentshield-security-review on .claude/** and .vibekit/skills/**." |
-| `autoresearch-coding` | Improving the repo through measured experiments. | "Use autoresearch-coding. Metric: `npm test`. Direction: higher. Budget: 3." |
-| `daily-workflow-curator` | Periodic tune-up of rules, skills, and workflows (propose-only). | "Use daily-workflow-curator and propose today's improvements." |
-| `path-sensitive-shell-safety` | Before editing shell/installer/deploy logic with path variables or `rm`/`mv`/`rsync`. | "Use path-sensitive-shell-safety before changing this cleanup script." |
-| `visual-design-loop` | UI polish: render → screenshot → review → fix, in a loop. | "Use visual-design-loop on /dashboard. Budget 3 loops." |
-| `clearthought` | Ambiguous requirements, design tradeoffs, risky decisions. | "Use clearthought. Operation: implementation_plan. Split this feature into safe tasks." |
-| `sequential-thinking` | Step-by-step decomposition of complex work. | "Use sequential-thinking. Break this refactor into ordered steps with tests." |
-| `reviewing-4p-priorities` | Triaging bugs/findings into P0–P4 fix order. | "Use reviewing-4p-priorities. Classify these findings and give a fix sequence." |
-| `memento` | Multi-day tasks: save context before stopping, resume next session. | "/memento — write MEMENTO.md with Goal, Done, Stuck, Next." |
-| `coding-level` | Setting how detailed explanations should be (0 = ELI5 … 5 = expert). | "/coding-level 2" |
-| `prompt-sharpener` | A complex task but only a rough prompt: sharpen it, then execute it in the same turn. | "/prompt-sharpener make the settings page load faster" |
+All 15 skills live canonically in `.vibekit/skills/`. Claude, Codex, and Grok mirror all 15; Cursor mirrors the 10 interactive ones. Invoke them by name ("Use the X skill…") or via the commands above.
+
+| Skill                         | Use it when                                                                                                                                                                                                                              | Example prompt                                                                                        |
+| ----------------------------- | ---------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------------- | ----------------------------------------------------------------------------------------------------- |
+| `vibekit-init`                | First-time setup, or `backbone.yml` / managed blocks need repair.                                                                                                                                                                        | "Use the vibekit-init skill. Propose one diff and wait for my yes."                                   |
+| `parallel-analysis`           | Repo-wide questions, large diff reviews, consistency audits.                                                                                                                                                                             | "Use parallel-analysis: where is auth handled and what depends on it?"                                |
+| `agentshield-security-review` | Auditing agent config, skills, hooks, MCP, commands before merge.                                                                                                                                                                        | "Use agentshield-security-review on .claude/** and .vibekit/skills/**."                               |
+| `autoresearch-coding`         | Improving the repo through measured experiments.                                                                                                                                                                                         | "Use autoresearch-coding. Metric: `npm test`. Direction: higher. Budget: 3."                          |
+| `daily-workflow-curator`      | Periodic tune-up of rules, skills, and workflows (propose-only).                                                                                                                                                                         | "Use daily-workflow-curator and propose today's improvements."                                        |
+| `path-sensitive-shell-safety` | Before editing shell/installer/deploy logic with path variables or `rm`/`mv`/`rsync`.                                                                                                                                                    | "Use path-sensitive-shell-safety before changing this cleanup script."                                |
+| `visual-design-loop`          | UI polish: render → screenshot → review → fix, in a loop.                                                                                                                                                                                | "Use visual-design-loop on /dashboard. Budget 3 loops."                                               |
+| `clearthought`                | Ambiguous requirements, design tradeoffs, risky decisions.                                                                                                                                                                               | "Use clearthought. Operation: implementation_plan. Split this feature into safe tasks."               |
+| `sequential-thinking`         | Step-by-step decomposition of complex work.                                                                                                                                                                                              | "Use sequential-thinking. Break this refactor into ordered steps with tests."                         |
+| `reviewing-4p-priorities`     | Triaging bugs/findings into P0–P4 fix order.                                                                                                                                                                                             | "Use reviewing-4p-priorities. Classify these findings and give a fix sequence."                       |
+| `memento`                     | Multi-day tasks: save context before stopping, resume next session.                                                                                                                                                                      | "/memento — write MEMENTO.md with Goal, Done, Stuck, Next."                                           |
+| `coding-level`                | Setting how detailed explanations should be (0 = ELI5 … 5 = expert).                                                                                                                                                                     | "/coding-level 2"                                                                                     |
+| `prompt-sharpener`            | A complex task but only a rough prompt: sharpen it, then execute it in the same turn.                                                                                                                                                    | "/prompt-sharpener make the settings page load faster"                                                |
+| `claim`                       | Bringing something new into the repo (skill, rule, convention, tool): vet sources against official docs, fit-check, confirm, integrate, document.                                                                                        | "/claim add the conventional-commits rule from https://www.npmjs.com/package/minimal-vibe-coding-kit" |
+| `tutien`                      | A private, stress-relieving xianxia classification game for coding progress: refined mystical prose around exact Git/chat evidence, isolated from unrelated conversational modes. User-invoked; `/tutien off` restores normal kit prose. | "/tutien preview sources=git,/path/to/export.jsonl"                                                   |
 
 ## Advanced
 
@@ -248,14 +252,14 @@ Publishing checklist: [.vibekit/init/PUSH_TO_GITHUB.md](.vibekit/init/PUSH_TO_GI
 <details>
 <summary><strong>Troubleshooting</strong></summary>
 
-| Symptom | Fix |
-| --- | --- |
-| Agent ignores the init flow | Re-run the installer, or copy [.vibekit/init/CLAUDE-template.md](.vibekit/init/CLAUDE-template.md) to `CLAUDE.md`. |
-| Agent re-asks to init every session | Run init and approve; confirm `meta.template_status: initialized` in `backbone.yml`. |
-| Wrong stack detected | Remove stale lockfiles, or edit `backbone.yml` directly. |
-| Agent touches a path it shouldn't | Add the path to `policy.protected_paths` in `backbone.yml` (globs supported). |
-| AgentShield probe warning | Install Python 3, or ignore — it is a warning, not a failure. |
-| Scripts missing after install | Re-run install with `--force`, or copy `.vibekit/scripts/` manually. |
+| Symptom                             | Fix                                                                                                                |
+| ----------------------------------- | ------------------------------------------------------------------------------------------------------------------ |
+| Agent ignores the init flow         | Re-run the installer, or copy [.vibekit/init/CLAUDE-template.md](.vibekit/init/CLAUDE-template.md) to `CLAUDE.md`. |
+| Agent re-asks to init every session | Run init and approve; confirm `meta.template_status: initialized` in `backbone.yml`.                               |
+| Wrong stack detected                | Remove stale lockfiles, or edit `backbone.yml` directly.                                                           |
+| Agent touches a path it shouldn't   | Add the path to `policy.protected_paths` in `backbone.yml` (globs supported).                                      |
+| AgentShield probe warning           | Install Python 3, or ignore — it is a warning, not a failure.                                                      |
+| Scripts missing after install       | Re-run install with `--force`, or copy `.vibekit/scripts/` manually.                                               |
 
 </details>
 
@@ -270,4 +274,4 @@ Issues and PRs welcome at [`giang6283623/minimal-vibe-coding-kit`](https://githu
 
 MIT. See [LICENSE](LICENSE).
 
-> 🇻🇳 *If you love Vietnam and its people, you are fully free to use everything in here at no cost.*
+> 🇻🇳 _If you love Vietnam and its people, you are fully free to use everything in here at no cost._

package/docs/README.vi.md

@@ -1,12 +1,12 @@
 <div align="center">
 
-**Đọc bằng:** [English](../README.md) · **Tiếng Việt**
+**Đọc bằng:** [English](../README.md) · **Tiếng Việt** · [简体中文](README.zh-CN.md)
 
 # Minimal Vibe Coding Kit
 
 [![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](../LICENSE)
 [![npm](https://img.shields.io/badge/npm-minimal--vibe--coding--kit-cb3837?logo=npm)](https://www.npmjs.com/package/minimal-vibe-coding-kit)
-[![Version](https://img.shields.io/badge/version-0.4.2-2ea44f.svg)](../CHANGELOG.md)
+[![Version](https://img.shields.io/badge/version-0.5.0-2ea44f.svg)](../CHANGELOG.md)
 ![Claude](https://img.shields.io/badge/Claude%20Code-Commands%20%26%20Skills-111111)
 ![Cursor](https://img.shields.io/badge/Cursor-Rules%20%26%20Commands-1f6feb)
 ![Codex](https://img.shields.io/badge/Codex-AGENTS.md%20%26%20Plugin-6f42c1)
@@ -145,11 +145,13 @@ Bạn (prompt) ──▶ Claude Code / Cursor / Codex / Grok
 1. **Cứ code bình thường.** Yêu cầu feature/fix như thường lệ; agent theo quy ước trong `backbone.yml` và giữ diff nhỏ.
 2. **Task lớn hoặc mơ hồ?** Bắt đầu với skill `clearthought` hoặc `sequential-thinking` để có kế hoạch trước.
 3. **Task phức tạp nhưng prompt mù mờ?** `/prompt-sharpener <prompt mù mờ>` cải thiện prompt thành bản rõ ràng rồi thực thi ngay trong cùng lượt.
-4. **Câu hỏi toàn repo hoặc review lớn?** Dùng `parallel-analysis` — chia các lane phân tích chỉ-đọc chạy song song rồi xác minh kết quả gộp.
-5. **Đã sửa `.claude/`, skills, hooks, hoặc script installer?** Chạy `/security-scan` trước khi merge.
-6. **Muốn cải tiến đo được?** Chạy `/autoresearch-coding` với metric và budget.
-7. **Giữ setup luôn sắc bén:** `/daily-enhance` đề xuất cải tiến — không bao giờ tự áp dụng.
-8. **Onboarding xong hẳn?** `/vibe-finalize` dọn các file bootstrap một lần.
+4. **Muốn đưa skill, rule, hoặc tool mới vào repo?** `/claim <yêu cầu + link>` kiểm chứng nguồn với tài liệu chính thức, kiểm tra độ khớp với repo, hỏi lại khi chưa rõ, rồi tích hợp và ghi tài liệu.
+5. **Muốn thả lỏng một chút khi nhìn lại tiến độ?** `/tutien` là trò chơi phân loại tu tiên lành mạnh, riêng tư dựa trên lịch sử Git + file export chat AI. Giọng văn huyền nhã bao quanh số liệu thật về cảnh giới, token và thói quen làm việc; `/tutien off` khôi phục văn phong bình thường của kit.
+6. **Câu hỏi toàn repo hoặc review lớn?** Dùng `parallel-analysis` — chia các lane phân tích chỉ-đọc chạy song song rồi xác minh kết quả gộp.
+7. **Đã sửa `.claude/`, skills, hooks, hoặc script installer?** Chạy `/security-scan` trước khi merge.
+8. **Muốn cải tiến đo được?** Chạy `/autoresearch-coding` với metric và budget.
+9. **Giữ setup luôn sắc bén:** `/daily-enhance` đề xuất cải tiến — không bao giờ tự áp dụng.
+10. **Onboarding xong hẳn?** `/vibe-finalize` dọn các file bootstrap một lần.
 
 ## Commands
 
@@ -164,7 +166,7 @@ Bạn (prompt) ──▶ Claude Code / Cursor / Codex / Grok
 
 ## Skills
 
-Cả 13 skill nằm trong `.vibekit/skills/` và được mirror cho từng tool. Gọi bằng tên ("Use the X skill…") hoặc qua các command ở trên.
+Cả 15 skill nằm canonical trong `.vibekit/skills/`. Claude, Codex và Grok mirror đủ 15; Cursor mirror 10 skill tương tác. Gọi bằng tên ("Use the X skill…") hoặc qua các command ở trên.
 
 | Skill                         | Dùng khi                                                                              | Prompt ví dụ                                                                            |
 | ----------------------------- | ------------------------------------------------------------------------------------- | --------------------------------------------------------------------------------------- |
@@ -181,6 +183,8 @@ Cả 13 skill nằm trong `.vibekit/skills/` và được mirror cho từng tool
 | `memento`                     | Task nhiều ngày: lưu ngữ cảnh trước khi dừng, resume phiên sau.                       | "/memento — write MEMENTO.md with Goal, Done, Stuck, Next."                             |
 | `coding-level`                | Chỉnh độ chi tiết khi giải thích (0 = ELI5 … 5 = chuyên gia).                         | "/coding-level 2"                                                                       |
 | `prompt-sharpener`            | Task phức tạp nhưng prompt mù mờ: cải thiện prompt rồi thực thi ngay trong cùng lượt. | "/prompt-sharpener make the settings page load faster"                                  |
+| `claim`                       | Đưa thứ mới vào repo (skill, rule, quy ước, tool): kiểm chứng nguồn chính thức, kiểm tra độ khớp, xác nhận, tích hợp, ghi tài liệu. | "/claim add the conventional-commits rule from https://www.conventionalcommits.org"     |
+| `tutien`                      | Trò chơi phân loại tu tiên riêng tư, giúp thư giãn khi nhìn lại tiến độ code; văn phong huyền nhã bao quanh bằng chứng Git/chat chính xác và tách biệt với các chế độ hội thoại khác. User-invoked; `/tutien off` khôi phục văn phong bình thường. | "/tutien preview sources=git,/path/to/export.jsonl"                                     |
 
 ## Nâng cao
 

package/docs/README.zh-CN.md

@@ -0,0 +1,277 @@
+<div align="center">
+
+**阅读语言：** [English](../README.md) · [Tiếng Việt](README.vi.md) · **简体中文**
+
+# Minimal Vibe Coding Kit
+
+[![License: MIT](https://img.shields.io/badge/license-MIT-blue.svg)](../LICENSE)
+[![npm](https://img.shields.io/badge/npm-minimal--vibe--coding--kit-cb3837?logo=npm)](https://www.npmjs.com/package/minimal-vibe-coding-kit)
+[![Version](https://img.shields.io/badge/version-0.5.0-2ea44f.svg)](../CHANGELOG.md)
+![Claude](https://img.shields.io/badge/Claude%20Code-Commands%20%26%20Skills-111111)
+![Cursor](https://img.shields.io/badge/Cursor-Rules%20%26%20Commands-1f6feb)
+![Codex](https://img.shields.io/badge/Codex-AGENTS.md%20%26%20Plugin-6f42c1)
+![Grok](https://img.shields.io/badge/Grok-Rules%20%26%20Skills-000000)
+![AgentShield](https://img.shields.io/badge/Security-AgentShield-d62828)
+![Node](https://img.shields.io/badge/node-%3E%3D18-339933?logo=node.js&logoColor=white)
+
+**一套可安装的 AI 编程工作流工具包，同时支持 Claude Code、Cursor、Codex 和 Grok——适用于任何仓库、任何语言。**
+
+安装 → 粘贴一个提示词 → 审核方案 → 在护栏保护下开始编码。
+
+</div>
+
+---
+
+## 这是什么？
+
+这是一套精简的共享 **规则（rules）**、**技能（skills）** 和 **命令（commands）**，再配合一个 **`backbone.yml`** 清单，让 Claude Code、Cursor、Codex 和 Grok 以一致的方式理解你的项目。
+
+- 绝不会覆盖已有的 `CLAUDE.md` 或 `AGENTS.md`，只会添加受管理的区块。
+- 初始化期间的每一次写入都会等待你的明确批准。
+- 对 Agent 表面进行安全审查（AgentShield）是标准工作流的一部分。
+- 默认安全删除：所有 Agent 优先使用可恢复的 `trash` 命令。初始化会检查它是否可用，并在缺失时给出安装建议；同时配合各工具官方支持的护栏配置——Claude Code 拒绝规则（`.claude/settings.json`）、Cursor CLI 权限（`.cursor/cli.json`）、Codex 执行策略规则（`.codex/rules/`，实验性，需要先信任项目）以及 Grok 项目权限规则（`.grok/config.toml`）。
+- 首次初始化会询问两个偏好：是否用 `trash` 代替 `rm`，以及默认解释级别（0–5，可随时通过 `/coding-level N` 修改），然后将它们记录到 `backbone.yml`。
+
+## 快速开始
+
+三个步骤，大约两分钟。
+
+**1. 安装到你的项目中**（无需克隆仓库）：
+
+```bash
+npx --yes minimal-vibe-coding-kit@latest install /path/to/your-project
+```
+
+已经运行过 `npm i minimal-vibe-coding-kit`，或者更喜欢 GitHub / 本地克隆方式？请参阅[从 npm 安装](#从-npm-安装)。
+
+**2. 在 Claude Code、Cursor、Codex 或 Grok 中打开项目并粘贴：**
+
+```text
+Read .vibekit/init/FIRST_TIME_INIT.md and initialize this repo with Minimal Vibe Coding Kit.
+First print the requirements you will check. Then run detection, propose one diff
+for backbone.yml and managed instruction blocks, and wait for my yes before writing.
+```
+
+**3. 审核提出的差异并回复 `yes`。**
+
+Agent 会使用检测到的技术栈和约定填写 `backbone.yml`，并将状态改为 `initialized`。完成后，之后的每个会话都会自动读取它并跳过初始化。
+
+你可以随时运行健康检查：
+
+```bash
+node .vibekit/scripts/mvck.mjs doctor .
+```
+
+## 从 npm 安装
+
+工具包以 [`minimal-vibe-coding-kit`](https://www.npmjs.com/package/minimal-vibe-coding-kit) 的名称发布到 npm。它是一个**脚手架 CLI，而不是代码库依赖**——仅仅放在 `node_modules/` 中不会自动生效。运行一次 `install`，才会像 GitHub 安装方式一样把工具包复制到你的仓库根目录。
+
+**方式 A——一次性运行（推荐）。** 不会向项目依赖中添加任何内容：
+
+```bash
+npx --yes minimal-vibe-coding-kit@latest install /path/to/your-project
+```
+
+**方式 B——作为开发依赖安装。** 如果工具包已经存在或将要加入你的 `package.json`，还需要再执行一个命令：
+
+```bash
+npm i -D minimal-vibe-coding-kit
+npx mvck install .        # 必需——将工具包从 node_modules 复制到仓库中
+```
+
+> **重要：** 单独运行 `npm i` 只会把工具包下载到 `node_modules/`，此时任何功能都尚未启用。
+> `mvck install` 才会把 `.claude/`、`.cursor/`、`.agents/`、`.vibekit/` 和 `backbone.yml` 复制到仓库根目录。
+
+之后可以通过 `npx` 使用简短命令 `mvck`（别名：`vibe-kit`）：
+
+| 简短命令                  | 作用                                                             |
+| ------------------------- | ---------------------------------------------------------------- |
+| `npx mvck install .`      | 将工具包复制到仓库（`--profile`、`--dry-run`、`--force`）        |
+| `npx mvck update .`       | 在新版本发布后刷新工具包拥有的文件                               |
+| `npx mvck doctor .`       | 只读健康检查                                                     |
+| `npx mvck validate .`     | 验证目录和配置结构                                               |
+
+然后继续执行快速开始的**第 2 步**（粘贴初始化提示词）。
+
+其他安装方式：`npx github:giang6283623/minimal-vibe-coding-kit install /path/to/your-project`，或者在本地克隆中运行 `./install.sh /path/to/your-project`（Windows：`./install.ps1 -Target C:\path\to\your-project`）。
+
+## 安装后仓库中会出现什么
+
+安装只会添加以下内容，不会触碰项目中的其他文件：
+
+```text
+your-project/
+├── backbone.yml              ← Agent 首先读取的项目地图（唯一事实来源）
+├── AGENTS.md                 ← 共享 Agent 指令（受管理区块）
+├── CLAUDE.md                 ← 简短入口；导入 AGENTS.md（仅在缺失时创建）
+├── .gitignore                ← 在受管理区块中追加工具包条目
+├── .claude/                  ← Claude Code：规则、命令、Agent、技能
+├── .cursor/                  ← Cursor：规则、命令、技能
+├── .agents/                  ← Codex / 可移植技能
+├── .codex/  .codex-plugin/   ← Codex 配置示例和插件清单
+├── .grok/                    ← Grok Build：规则、技能、配置示例
+└── .vibekit/                 ← 工具包拥有的所有内容都集中在一个目录
+    ├── skills/               ← 规范技能源（镜像到各工具目录）
+    ├── commands/             ← 共享命令提示词
+    ├── scripts/              ← mvck CLI、初始化、验证、doctor、安全探针
+    ├── docs/                 ← 深入参考资料
+    └── init/                 ← 一次性引导文件（可通过 /vibe-finalize 移除）
+```
+
+已有文件绝不会被替换。工具包只会合并受管理区块（`BEGIN/END: minimal-vibe-coding-kit`），并跳过你自己拥有的内容。
+
+## 各部分如何连接
+
+```text
+你（提示词）──▶ Claude Code / Cursor / Codex / Grok
+                      │  首先读取
+                      ▼
+        backbone.yml  +  AGENTS.md / CLAUDE.md  +  rules
+                      │  按需加载
+                      ▼
+        skills（流程） +  commands（快捷入口）
+                      │  受以下机制保护
+                      ▼
+        protected paths · 写入前提案 · AgentShield probe
+```
+
+- **`backbone.yml`**——仓库路径、约定、受保护路径以及验证命令。
+- **规则（Rules）**——始终加载的短护栏，例如先读取 backbone、保持差异小、修改 Agent 表面时执行安全审查。
+- **技能（Skills）**——可重复执行的工作流程，只在任务需要时加载。
+- **命令（Commands）**——常用技能的一词快捷入口。
+
+## 日常使用指南
+
+1. **正常提出编码需求。** 像平时一样请求功能或修复；Agent 会遵循 `backbone.yml` 中的约定，并保持差异小而易审查。
+2. **任务很大或不够明确？** 先使用 `clearthought` 或 `sequential-thinking` 技能生成计划。
+3. **任务复杂，但只有一个粗略提示词？** `/prompt-sharpener <rough prompt>` 会将它变得清晰准确，并在同一轮中执行。
+4. **想把新技能、规则或工具带入仓库？** `/claim <request + links>` 会根据官方文档验证来源、检查是否适合当前仓库、在不明确时询问，然后完成集成和文档记录。
+5. **想在回顾进度时安静地放松一下？** `/tutien` 是一款私密、健康的修仙风格分类游戏，分析 Git 历史和你明确提供的 AI 聊天导出。它以清雅玄妙的文风呈现境界、token 使用和工作流习惯，但绝不改变证据；`/tutien off` 会恢复工具包的正常文风。
+6. **需要回答全仓库问题或进行大型审查？** 使用 `parallel-analysis`，它会并行执行多个只读分析通道，并验证合并后的结论。
+7. **修改了 `.claude/`、技能、hook 或安装脚本？** 合并前运行 `/security-scan`。
+8. **想进行可衡量的改进？** 使用带有 metric 和预算的 `/autoresearch-coding`。
+9. **保持配置清晰可靠：** `/daily-enhance` 只提出改进建议，绝不会静默应用。
+10. **引导工作已经彻底完成？** `/vibe-finalize` 会移出一次性 bootstrap 文件。
+
+## 命令
+
+| 命令                     | 作用                                                               | 示例                                                               |
+| ------------------------ | ------------------------------------------------------------------ | ------------------------------------------------------------------ |
+| `/init-vibe`             | 首次初始化或修复：提出一个差异并等待批准。                         | `/init-vibe`——审核差异后回复 `yes`。                               |
+| `/security-scan`         | 对 Agent 表面执行只读 AgentShield 探针和可选完整扫描。              | 修改 `.claude/**` 或技能后，在合并前运行 `/security-scan`。         |
+| `/daily-enhance`         | 生成仅供提案的规则、技能和工作流改进报告。                         | `/daily-enhance`——审核提出的差异后再批准。                         |
+| `/autoresearch-coding`   | 带基线、指标和预算的实验循环。                                     | `/autoresearch-coding` Goal: fewer lint errors. Budget: 3.         |
+| `/council`               | 协调 reviewer、researcher 和 analyst Agent，形成一个统一计划。      | `/council` on this branch diff.                                    |
+| `/vibe-finalize`         | 让项目完成引导：将一次性文件移到 `_vibekit-cleanup/`。              | `/vibe-finalize`——先预览，批准后再应用。                           |
+
+## 技能
+
+全部 15 个技能的规范版本位于 `.vibekit/skills/`。Claude、Codex 和 Grok 镜像全部 15 个技能；Cursor 镜像其中 10 个交互式技能。可以直接按名称调用（例如“Use the X skill…”），也可以使用上面的命令。
+
+| 技能                            | 适用场景                                                                                             | 示例提示词                                                                                              |
+| ------------------------------- | ---------------------------------------------------------------------------------------------------- | ------------------------------------------------------------------------------------------------------- |
+| `vibekit-init`                  | 首次设置，或需要修复 `backbone.yml` / 受管理区块。                                                   | "Use the vibekit-init skill. Propose one diff and wait for my yes."                                   |
+| `parallel-analysis`             | 全仓库问题、大型差异审查、一致性审计。                                                               | "Use parallel-analysis: where is auth handled and what depends on it?"                                |
+| `agentshield-security-review`   | 合并前审计 Agent 配置、技能、hook、MCP 和命令。                                                       | "Use agentshield-security-review on .claude/** and .vibekit/skills/**."                               |
+| `autoresearch-coding`           | 通过可衡量的实验持续改进仓库。                                                                       | "Use autoresearch-coding. Metric: `npm test`. Direction: higher. Budget: 3."                          |
+| `daily-workflow-curator`        | 定期调整规则、技能和工作流（仅提案）。                                                               | "Use daily-workflow-curator and propose today's improvements."                                        |
+| `path-sensitive-shell-safety`   | 修改包含路径变量或 `rm`/`mv`/`rsync` 的 shell、安装或部署逻辑之前。                                  | "Use path-sensitive-shell-safety before changing this cleanup script."                                |
+| `visual-design-loop`            | UI 打磨：渲染 → 截图 → 审查 → 修复，循环进行。                                                       | "Use visual-design-loop on /dashboard. Budget 3 loops."                                               |
+| `clearthought`                  | 需求模糊、存在设计取舍或高风险决策。                                                                 | "Use clearthought. Operation: implementation_plan. Split this feature into safe tasks."               |
+| `sequential-thinking`           | 将复杂工作拆解为有序步骤。                                                                           | "Use sequential-thinking. Break this refactor into ordered steps with tests."                         |
+| `reviewing-4p-priorities`       | 按 P0–P4 对缺陷和发现进行排序。                                                                      | "Use reviewing-4p-priorities. Classify these findings and give a fix sequence."                       |
+| `memento`                       | 跨多日任务：停止前保存上下文，下一会话恢复。                                                         | "/memento — write MEMENTO.md with Goal, Done, Stuck, Next."                                           |
+| `coding-level`                  | 设置解释详细程度（0 = ELI5，5 = 专家同行）。                                                        | "/coding-level 2"                                                                                     |
+| `prompt-sharpener`              | 复杂任务只有粗略提示词时：优化提示词并在同一轮执行。                                                 | "/prompt-sharpener make the settings page load faster"                                                |
+| `claim`                         | 将新技能、规则、约定或工具带入仓库：验证官方来源、检查适配性、确认、集成并记录文档。                 | "/claim add the conventional-commits rule from https://www.conventionalcommits.org"                   |
+| `tutien`                        | 私密、舒缓压力的修仙编码进度分类游戏：以清雅玄妙的叙事包裹准确的 Git/聊天证据，并与其他对话模式隔离。仅由用户调用；`/tutien off` 恢复正常文风。 | "/tutien preview sources=git,/path/to/export.jsonl"                                                   |
+
+## 高级用法
+
+### 安装配置档
+
+只安装你使用的工具表面（默认为 `all`）：
+
+```bash
+npx --yes minimal-vibe-coding-kit@latest install . --profile claude          # 仅 Claude Code
+npx --yes minimal-vibe-coding-kit@latest install . --profile claude,cursor   # Claude + Cursor
+npx --yes minimal-vibe-coding-kit@latest install . --profile codex           # Codex / AGENTS.md Agent
+npx --yes minimal-vibe-coding-kit@latest install . --profile grok            # Grok Build CLI
+```
+
+选项：`--force`（覆盖已有的工具包文件）、`--dry-run`（预览）、`--json`（机器可读计划）。
+
+### 更新已安装的项目
+
+当工具包发布新技能或脚本后，在项目中运行：
+
+```bash
+npx --yes minimal-vibe-coding-kit@latest update . --dry-run   # 预览
+npx --yes minimal-vibe-coding-kit@latest update .             # 应用
+```
+
+`update` 只刷新**工具包拥有的文件**，绝不会触碰 `backbone.yml` 或你自己的内容。它会原位更新受管理区块，并将变更前的文件备份到 `.vibekit/update-backup/<timestamp>/`。详情请参阅 [.vibekit/docs/INSTALL.md](../.vibekit/docs/INSTALL.md)。
+
+### Autoresearch 循环
+
+```text
+Use the autoresearch-coding skill.
+Goal: improve maintainability. Metric command: <your validate command>. Direction: higher.
+Editable paths: src/ docs/. Protected paths: .git .env* node_modules lockfiles.
+Budget: 3.
+```
+
+约定：先建立基线 → 每次只进行一个小实验 → 只保留指标改善的变更 → 记录所有实验。
+
+### 安全审查（AgentShield）
+
+```bash
+node .vibekit/scripts/agentshield-probe.mjs .                          # 快速只读探针
+npx ecc-agentshield scan --path . --format text --min-severity medium  # 可选完整扫描
+```
+
+对 `CLAUDE.md`、`AGENTS.md`、`.claude/**`、`.cursor/**`、`.agents/**`、`.grok/**`、`.codex-plugin/**` 或 `.vibekit/skills|commands|scripts/**` 的任何修改都应触发安全审查。安全模型：[.vibekit/docs/SECURITY_MODEL.md](../.vibekit/docs/SECURITY_MODEL.md)。
+
+### Doctor 和报告
+
+```bash
+node .vibekit/scripts/mvck.mjs doctor .                 # 只读健康检查
+node .vibekit/scripts/mvck.mjs doctor . --write-report  # 写入 VIBE_REPORT.md
+node .vibekit/scripts/daily-enhance.mjs . --write-report
+```
+
+### 面向工具包开发者
+
+```bash
+npm test                # 语法 + 真实临时目录安装测试 + 结构验证
+npm run validate:all    # npm test + AgentShield 探针 + npm 打包预检
+```
+
+发布检查清单：[.vibekit/init/PUSH_TO_GITHUB.md](../.vibekit/init/PUSH_TO_GITHUB.md)。深入文档：[.vibekit/docs/](../.vibekit/docs/)。
+
+<details>
+<summary><strong>故障排除</strong></summary>
+
+| 症状                               | 解决方法                                                                                                                 |
+| ---------------------------------- | ------------------------------------------------------------------------------------------------------------------------ |
+| Agent 忽略初始化流程               | 重新运行安装程序，或将 [.vibekit/init/CLAUDE-template.md](../.vibekit/init/CLAUDE-template.md) 复制为 `CLAUDE.md`。       |
+| Agent 每个会话都重新要求初始化     | 运行并批准初始化；确认 `backbone.yml` 中存在 `meta.template_status: initialized`。                                      |
+| 检测到错误的技术栈                 | 删除过期 lockfile，或直接编辑 `backbone.yml`。                                                                          |
+| Agent 修改了不应触碰的路径         | 将该路径加入 `backbone.yml` 的 `policy.protected_paths`（支持 glob）。                                                   |
+| AgentShield 探针发出警告           | 安装 Python 3，或者忽略；这是 warning，不是 failure。                                                                    |
+| 安装后缺少脚本                     | 使用 `--force` 重新安装，或手动复制 `.vibekit/scripts/`。                                                                |
+
+</details>
+
+## 贡献
+
+欢迎在 [`giang6283623/minimal-vibe-coding-kit`](https://github.com/giang6283623/minimal-vibe-coding-kit) 提交 Issue 和 PR。提交 PR 前，请在 `.claude/`、`.cursor/`、`.agents/` 之间同步技能变更，保持模板与具体项目无关，并运行 `npm run validate:all`。另请参阅 [CONTRIBUTING.md](../CONTRIBUTING.md)、[SECURITY.md](../SECURITY.md) 和 [CODE_OF_CONDUCT.md](../CODE_OF_CONDUCT.md)。
+
+**创建者：** [GiangBV](https://www.linkedin.com/in/buivangiang1992)、[AuPMH](https://www.linkedin.com/in/pham-au-2a1bb1162)  
+**技术动力：** 咖啡因、坚持、与 AI 协作，以及周末的编程时光。
+
+## 许可证
+
+MIT。请参阅 [LICENSE](../LICENSE)。
+
+> 🇻🇳 _如果你热爱越南和越南人民，你可以完全免费使用这里的一切。_

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "minimal-vibe-coding-kit",
-  "version": "0.4.2",
+  "version": "0.5.0",
   "description": "Project-agnostic AI coding workflow kit for Claude Code, Cursor, Codex, and Grok with AgentShield security review.",
   "type": "module",
   "bin": {
@@ -15,12 +15,13 @@
     "daily": "node .vibekit/scripts/daily-enhance.mjs . --write-report",
     "check:syntax": "node --check .vibekit/scripts/mvck.mjs && node --check .vibekit/scripts/init-backbone.mjs && node --check .vibekit/scripts/daily-enhance.mjs && node --check .vibekit/scripts/validate-kit.mjs && node --check .vibekit/scripts/doctor.mjs && node --check .vibekit/scripts/test-install.mjs && node --check .vibekit/scripts/agentshield-probe.mjs && node --check .vibekit/scripts/pack-dry-run.mjs && node --check .vibekit/scripts/vibekit-finalize.mjs && node --check bin/mvck.js && node --check bin/vibe-kit.js",
     "test:install": "node .vibekit/scripts/test-install.mjs",
-    "test": "npm run check:syntax && npm run test:install && npm run validate",
+    "test": "npm run check:syntax && npm run test:install && npm run validate && npm run test:tutien",
     "validate": "node .vibekit/scripts/validate-kit.mjs .",
     "security:probe": "node .vibekit/scripts/agentshield-probe.mjs .",
     "pack:dry-run": "node .vibekit/scripts/pack-dry-run.mjs",
     "validate:all": "npm test && npm run security:probe && npm run pack:dry-run",
-    "pack:repo": "node .vibekit/scripts/validate-kit.mjs . && npm pack"
+    "pack:repo": "node .vibekit/scripts/validate-kit.mjs . && npm pack",
+    "test:tutien": "node test/tutien/scripts/test-analyzer.mjs && node test/tutien/scripts/test-render.mjs && node test/tutien/scripts/test-villains.mjs && node test/tutien/scripts/test-snapshot.mjs && node test/tutien/scripts/test-classify.mjs && node test/tutien/scripts/test-adversarial.mjs && node test/tutien/scripts/test-e2e.mjs"
   },
   "keywords": [
     "vibe-coding",
@@ -58,6 +59,8 @@
     ".claude/skills/coding-level/",
     ".claude/skills/parallel-analysis/",
     ".claude/skills/prompt-sharpener/",
+    ".claude/skills/claim/",
+    ".claude/skills/tutien/",
     ".cursor/rules/",
     ".cursor/commands/",
     ".cursor/settings.json",
@@ -70,6 +73,8 @@
     ".cursor/skills/coding-level/",
     ".cursor/skills/parallel-analysis/",
     ".cursor/skills/prompt-sharpener/",
+    ".cursor/skills/claim/",
+    ".cursor/skills/tutien/",
     ".agents/",
     ".grok/",
     ".codex/",
@@ -84,6 +89,7 @@
     "install.ps1",
     "README.md",
     "docs/README.vi.md",
+    "docs/README.zh-CN.md",
     "SECURITY.md",
     "CONTRIBUTING.md",
     "CODE_OF_CONDUCT.md",