jvibe 1.0.0

package/JVIBE.md

@@ -0,0 +1,75 @@
+<!-- JVIBE:START -->
+# JVibe Instructions
+
+这是 JVibe 文档驱动开发系统的 AI 入口文档。
+
+## 何时使用 JVibe 工作流
+
+当用户请求涉及以下场景时，自动使用对应的 JVibe Skill 或 Agent：
+
+| 场景 | 使用 |
+|------|------|
+| 新项目初始化 | `/JVibe:init` |
+| 需求分析、功能规划 | `planner` agent |
+| 代码实现、TODO 完成 | `developer` agent |
+| 代码审查、规范检查 | `reviewer` agent |
+| 文档状态同步 | `doc-sync` agent |
+| 查看项目状态 | `/JVibe:status` |
+| 生成 PR 描述 | `/JVibe:pr` |
+
+## 核心概念
+
+### 1. 文档体系
+
+JVibe 使用两类文档：
+
+**CORE-DOCS（4个固定核心文档）**：
+- `docs/core/规范文档.md` - 入口和索引
+- `docs/core/项目文档.md` - 架构与模块边界
+- `docs/core/功能清单.md` - **功能状态唯一来源（SoT）**
+- `docs/core/附加材料.md` - 规范索引
+
+**PROJECT-DOCS（按需创建）**：
+- `docs/project/*.md` - API文档、数据库文档等
+- 必须在规范文档中注册
+
+### 2. 单一事实来源（SoT）
+
+**重要**：功能状态只在 `功能清单.md` 中维护！
+
+状态推导规则：
+```
+TODO 完成情况 → 功能状态
+┌─────────────────────────────────────┐
+│  完成数 / 总数  │  推导状态  │  状态符号   │
+├─────────────────┼────────────┼─────────────┤
+│     0 / N       │   未开始   │     ❌      │
+│   1~(N-1) / N   │   开发中   │     🚧      │
+│     N / N       │   已完成   │     ✅      │
+└─────────────────────────────────────────────┘
+```
+
+### 3. 开发流程
+
+```
+需求分析 → 功能拆解 → 技术设计 → 编码实现 → 代码审查 → 文档同步
+```
+
+## Agent 职责
+
+| Agent | 职责 | 可写文件 |
+|-------|------|----------|
+| **planner** | 需求分析、功能拆解、创建 F-XXX 条目 | 功能清单.md |
+| **developer** | 代码实现、逐项完成 TODO、勾选完成项 | 功能清单.md + 源代码 |
+| **reviewer** | 代码审查、规范检查、PR 描述生成 | 只读 |
+| **doc-sync** | 状态推导、统计更新、格式检查 | 项目文档.md |
+
+## 重要提示
+
+1. **先读文档再开发**：开发前先阅读 `规范文档.md` 了解项目结构
+2. **遵循 SoT 原则**：功能状态只更新 `功能清单.md`
+3. **查阅附加材料**：开发前检查 `附加材料.md` 中的相关规范
+4. **注册 PROJECT-DOCS**：新建项目文档必须在规范文档中注册
+
+保持此管理块，以便 `jvibe upgrade` 更新指令。
+<!-- JVIBE:END -->

package/LICENSE

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 JVibe
+
+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,175 @@
+# JVibe
+
+> 文档驱动的 AI 辅助开发系统
+
+[![npm version](https://badge.fury.io/js/jvibe.svg)](https://badge.fury.io/js/jvibe)
+[![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
+
+---
+
+## 📌 什么是 JVibe？
+
+JVibe 是一个**文档驱动的 AI 辅助开发系统**，专为 Claude Code 设计。它提供：
+
+- 🤖 **4 个专业 Agent**：需求规划、代码开发、代码审查、文档同步
+- 📝 **结构化文档体系**：CORE-DOCS（4个核心文档）+ PROJECT-DOCS（按需扩展）
+- 🔄 **自动化 Hooks**：自动加载上下文、同步功能状态、输出统计信息
+- 🎯 **单一事实来源**：功能状态只在功能清单中维护（SoT 原则）
+
+---
+
+## 🚀 快速开始
+
+### 安装
+
+```bash
+# 全局安装
+npm install -g jvibe
+
+# 或使用 npx
+npx jvibe init
+```
+
+### 初始化项目
+
+```bash
+cd your-project
+jvibe init
+
+# 或最小化安装（仅 Core 文档）
+jvibe init --mode=minimal
+```
+
+### 开始使用
+
+```bash
+# 在 Claude Code 中运行
+/JVibe:init     # 创建项目文档
+/JVibe:status   # 查看项目状态
+/JVibe:pr       # 生成 PR 描述
+```
+
+---
+
+## 📂 项目结构
+
+运行 `jvibe init` 后，你的项目将包含：
+
+```
+your-project/
+├── .claude/                    # Claude Code 配置
+│   ├── agents/                 # 4 个 Sub-Agents
+│   ├── commands/               # 3 个 JVibe Skills
+│   ├── hooks/                  # 3 个自动化 Hooks
+│   └── settings.json
+│
+├── docs/
+│   ├── core/                   # CORE-DOCS（4个固定核心文档）
+│   │   ├── 规范文档.md        # 入口和索引
+│   │   ├── 项目文档.md        # 架构与模块边界
+│   │   ├── 功能清单.md        # 功能状态唯一来源（SoT）
+│   │   └── 附加材料.md        # 规范索引
+│   │
+│   └── project/                # PROJECT-DOCS（按需创建）
+│       └── README.md
+│
+└── .gitignore
+```
+
+---
+
+## 📚 文档体系
+
+### CORE-DOCS vs PROJECT-DOCS
+
+| 维度 | CORE-DOCS | PROJECT-DOCS |
+|------|-----------|--------------|
+| **结构** | 所有项目相同 | 按需创建 |
+| **数量** | 固定 4 个 | 可变（0~N） |
+| **注册** | 自动存在 | 必须在规范文档中注册 |
+
+### 单一事实来源（SoT）
+
+功能状态只在 `功能清单.md` 中维护：
+
+```
+TODO 完成情况 → 功能状态
+┌─────────────────────────────────────┐
+│  完成数 / 总数  │  状态符号   │
+├─────────────────┼─────────────┤
+│     0 / N       │     ❌      │
+│   1~(N-1) / N   │     🚧      │
+│     N / N       │     ✅      │
+└─────────────────────────────────────┘
+```
+
+---
+
+## 🤖 Agent 架构
+
+| Agent | 职责 | 模型 |
+|-------|------|------|
+| **planner** | 需求分析、功能拆解 | Sonnet |
+| **developer** | 代码实现、TODO 完成 | Sonnet |
+| **reviewer** | 代码审查、规范检查 | Sonnet |
+| **doc-sync** | 状态推导、统计更新 | Haiku |
+
+---
+
+## 🔧 CLI 命令
+
+| 命令 | 说明 |
+|------|------|
+| `jvibe init` | 初始化 JVibe 项目 |
+| `jvibe init --mode=minimal` | 最小化初始化（仅 Core 文档） |
+| `jvibe init --force` | 强制覆盖已存在的配置 |
+| `jvibe upgrade` | 升级到最新版本 |
+| `jvibe upgrade --check` | 仅检查更新 |
+| `jvibe status` | 查看项目配置状态 |
+| `jvibe validate` | 验证项目配置 |
+
+---
+
+## 🎯 核心原则
+
+JVibe 基于以下原则设计：
+
+- **SOLID**：单一职责、开闭原则、里氏替换、接口隔离、依赖倒置
+- **DRY**：避免重复，功能状态只在一处维护
+- **KISS**：保持简单，状态推导规则清晰明确
+- **YAGNI**：只实现当前需要的功能
+
+---
+
+## 📖 文档
+
+- [快速开始指南](docs/GETTING_STARTED.md)
+- [CLI 命令参考](docs/CLI_COMMANDS.md)
+- [架构说明](docs/ARCHITECTURE.md)
+- [CORE vs PROJECT 文档](docs/CORE_VS_PROJECT_DOCS.md)
+- [贡献指南](docs/CONTRIBUTING.md)
+
+---
+
+## 🤝 贡献
+
+欢迎贡献！请查看 [贡献指南](docs/CONTRIBUTING.md)。
+
+1. Fork 本仓库
+2. 创建分支 `git checkout -b feature/improvement`
+3. 提交变更 `git commit -m 'feat: 添加新功能'`
+4. 推送分支 `git push origin feature/improvement`
+5. 创建 Pull Request
+
+---
+
+## 📄 许可证
+
+[MIT](LICENSE)
+
+---
+
+## 🔗 相关链接
+
+- [Claude Code 官方文档](https://docs.anthropic.com/claude-code)
+- [OpenSpec](https://github.com/openspec/openspec) - 灵感来源

package/bin/jvibe.js

@@ -0,0 +1,62 @@
+#!/usr/bin/env node
+
+/**
+ * JVibe CLI - 文档驱动的 AI 辅助开发系统
+ *
+ * 用法:
+ *   jvibe init [--mode=full|minimal]  初始化项目
+ *   jvibe upgrade                      升级到最新版本
+ *   jvibe status                       查看项目状态
+ *   jvibe validate                     验证项目配置
+ */
+
+const { Command } = require('commander');
+const pkg = require('../package.json');
+
+const program = new Command();
+
+program
+  .name('jvibe')
+  .description('JVibe - 文档驱动的 AI 辅助开发系统')
+  .version(pkg.version);
+
+// init 命令
+program
+  .command('init')
+  .description('初始化 JVibe 项目')
+  .option('--mode <type>', '模式: full（完整）或 minimal（最小）', 'full')
+  .option('--force', '强制覆盖已存在的文件', false)
+  .action(async (options) => {
+    const init = require('../scripts/init');
+    await init(options);
+  });
+
+// upgrade 命令
+program
+  .command('upgrade')
+  .description('升级到最新版本')
+  .option('--check', '仅检查更新，不执行升级', false)
+  .action(async (options) => {
+    const upgrade = require('../scripts/upgrade');
+    await upgrade(options);
+  });
+
+// status 命令
+program
+  .command('status')
+  .description('查看项目 JVibe 配置状态')
+  .action(async () => {
+    const status = require('../scripts/status');
+    await status();
+  });
+
+// validate 命令
+program
+  .command('validate')
+  .description('验证项目 JVibe 配置')
+  .action(async () => {
+    const validate = require('../scripts/validate');
+    await validate();
+  });
+
+program.parse();

package/package.json

@@ -0,0 +1,50 @@
+{
+  "name": "jvibe",
+  "version": "1.0.0",
+  "description": "文档驱动的 AI 辅助开发系统 - Doc-driven AI-assisted development system for Claude Code",
+  "main": "bin/jvibe.js",
+  "bin": {
+    "jvibe": "./bin/jvibe.js"
+  },
+  "scripts": {
+    "test": "echo \"No tests yet\""
+  },
+  "files": [
+    "bin/",
+    "scripts/",
+    "lib/",
+    "template/",
+    "JVIBE.md",
+    "README.md",
+    "LICENSE"
+  ],
+  "keywords": [
+    "claude",
+    "claude-code",
+    "ai",
+    "development",
+    "documentation",
+    "doc-driven",
+    "vibe-coding",
+    "agents",
+    "cli"
+  ],
+  "author": "9963KK",
+  "license": "MIT",
+  "repository": {
+    "type": "git",
+    "url": "git+https://github.com/9963KK/VibeCoding-Tech.git"
+  },
+  "bugs": {
+    "url": "https://github.com/9963KK/VibeCoding-Tech/issues"
+  },
+  "homepage": "https://github.com/9963KK/VibeCoding-Tech#readme",
+  "dependencies": {
+    "chalk": "^4.1.2",
+    "commander": "^11.1.0",
+    "fs-extra": "^11.2.0"
+  },
+  "engines": {
+    "node": ">=16.0.0"
+  }
+}

package/scripts/init.js

@@ -0,0 +1,118 @@
+/**
+ * JVibe Init Script
+ * 初始化项目的 JVibe 配置
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+const chalk = require('chalk');
+
+const TEMPLATE_DIR = path.join(__dirname, '../template');
+
+/**
+ * 初始化 JVibe 项目
+ * @param {Object} options - 初始化选项
+ * @param {string} options.mode - 模式: 'full' 或 'minimal'
+ * @param {boolean} options.force - 是否强制覆盖
+ */
+async function init(options = {}) {
+  const mode = options.mode || 'full';
+  const force = options.force || false;
+  const cwd = process.cwd();
+
+  console.log(chalk.blue('\n🚀 正在初始化 JVibe...\n'));
+
+  try {
+    // 1. 检查是否已存在 JVibe 配置
+    const claudeDir = path.join(cwd, '.claude');
+    if (await fs.pathExists(claudeDir) && !force) {
+      console.log(chalk.yellow('⚠️  检测到已存在 .claude/ 目录'));
+      console.log(chalk.yellow('   使用 --force 选项强制覆盖'));
+      return;
+    }
+
+    // 2. 复制 .claude/ 目录
+    console.log(chalk.gray('   复制 .claude/ 配置...'));
+    await fs.copy(
+      path.join(TEMPLATE_DIR, '.claude'),
+      claudeDir,
+      { overwrite: force }
+    );
+
+    // 3. 复制文档目录
+    if (mode === 'full') {
+      console.log(chalk.gray('   复制 docs/ 文档模板...'));
+      await fs.copy(
+        path.join(TEMPLATE_DIR, 'docs'),
+        path.join(cwd, 'docs'),
+        { overwrite: force }
+      );
+    } else {
+      // minimal 模式只复制 core 文档
+      console.log(chalk.gray('   复制 docs/core/ 核心文档...'));
+      await fs.ensureDir(path.join(cwd, 'docs'));
+      await fs.copy(
+        path.join(TEMPLATE_DIR, 'docs/core'),
+        path.join(cwd, 'docs/core'),
+        { overwrite: force }
+      );
+    }
+
+    // 4. 更新 .gitignore
+    const gitignorePath = path.join(cwd, '.gitignore');
+    const jvibeIgnore = '\n# JVibe\n.claude/settings.local.json\n';
+
+    if (await fs.pathExists(gitignorePath)) {
+      const content = await fs.readFile(gitignorePath, 'utf-8');
+      if (!content.includes('.claude/settings.local.json')) {
+        console.log(chalk.gray('   更新 .gitignore...'));
+        await fs.appendFile(gitignorePath, jvibeIgnore);
+      }
+    } else {
+      console.log(chalk.gray('   创建 .gitignore...'));
+      await fs.copy(
+        path.join(TEMPLATE_DIR, '.gitignore'),
+        gitignorePath
+      );
+    }
+
+    // 5. 添加版本信息到 settings.json
+    const settingsPath = path.join(claudeDir, 'settings.json');
+    if (await fs.pathExists(settingsPath)) {
+      const settings = await fs.readJson(settingsPath);
+      settings.jvibe = {
+        version: require('../package.json').version,
+        installedAt: new Date().toISOString(),
+        mode: mode
+      };
+      await fs.writeJson(settingsPath, settings, { spaces: 2 });
+    }
+
+    // 6. 输出成功信息
+    console.log(chalk.green('\n✅ JVibe 初始化完成！\n'));
+
+    console.log(chalk.white('已创建：'));
+    console.log(chalk.gray('  - .claude/agents/      (4 个 Sub-Agents)'));
+    console.log(chalk.gray('  - .claude/commands/    (3 个 JVibe Skills)'));
+    console.log(chalk.gray('  - .claude/hooks/       (3 个自动化 Hooks)'));
+    console.log(chalk.gray('  - .claude/settings.json'));
+
+    if (mode === 'full') {
+      console.log(chalk.gray('  - docs/core/           (4 个核心文档)'));
+      console.log(chalk.gray('  - docs/project/        (项目文档目录)'));
+    } else {
+      console.log(chalk.gray('  - docs/core/           (4 个核心文档)'));
+    }
+
+    console.log(chalk.yellow('\n📝 下一步：'));
+    console.log(chalk.white('  1. 在 Claude Code 中运行 /JVibe:init 创建项目文档'));
+    console.log(chalk.white('  2. 运行 /JVibe:status 查看项目状态'));
+    console.log(chalk.white('  3. 开始使用自然语言描述你的需求！\n'));
+
+  } catch (error) {
+    console.error(chalk.red('\n❌ 初始化失败：'), error.message);
+    process.exit(1);
+  }
+}
+
+module.exports = init;

package/scripts/status.js

@@ -0,0 +1,98 @@
+/**
+ * JVibe Status Script
+ * 查看项目的 JVibe 配置状态
+ */
+
+const fs = require('fs-extra');
+const path = require('path');
+const chalk = require('chalk');
+
+/**
+ * 显示 JVibe 状态
+ */
+async function status() {
+  const cwd = process.cwd();
+
+  console.log(chalk.blue('\n📊 JVibe 项目状态\n'));
+
+  try {
+    // 1. 检查 .claude 目录
+    const claudeDir = path.join(cwd, '.claude');
+    if (!await fs.pathExists(claudeDir)) {
+      console.log(chalk.red('❌ 未检测到 JVibe 配置'));
+      console.log(chalk.yellow('   请运行 jvibe init 初始化项目\n'));
+      return;
+    }
+
+    // 2. 读取版本信息
+    const settingsPath = path.join(claudeDir, 'settings.json');
+    let settings = {};
+    if (await fs.pathExists(settingsPath)) {
+      settings = await fs.readJson(settingsPath);
+    }
+
+    const jvibeInfo = settings.jvibe || {};
+
+    console.log(chalk.white('配置信息：'));
+    console.log(chalk.gray(`  版本:       ${jvibeInfo.version || '未知'}`));
+    console.log(chalk.gray(`  模式:       ${jvibeInfo.mode || '未知'}`));
+    console.log(chalk.gray(`  安装时间:   ${jvibeInfo.installedAt || '未知'}`));
+    if (jvibeInfo.upgradedAt) {
+      console.log(chalk.gray(`  升级时间:   ${jvibeInfo.upgradedAt}`));
+    }
+
+    // 3. 检查各组件状态
+    console.log(chalk.white('\n组件状态：'));
+
+    // Agents
+    const agentsDir = path.join(claudeDir, 'agents');
+    const agents = await fs.pathExists(agentsDir)
+      ? (await fs.readdir(agentsDir)).filter(f => f.endsWith('.md'))
+      : [];
+    console.log(chalk.gray(`  Agents:     ${agents.length > 0 ? chalk.green('✓') : chalk.red('✗')} (${agents.length} 个)`));
+
+    // Commands
+    const commandsDir = path.join(claudeDir, 'commands');
+    const commands = await fs.pathExists(commandsDir)
+      ? (await fs.readdir(commandsDir)).filter(f => f.endsWith('.md'))
+      : [];
+    console.log(chalk.gray(`  Commands:   ${commands.length > 0 ? chalk.green('✓') : chalk.red('✗')} (${commands.length} 个)`));
+
+    // Hooks
+    const hooksDir = path.join(claudeDir, 'hooks');
+    const hooks = await fs.pathExists(hooksDir)
+      ? (await fs.readdir(hooksDir)).filter(f => f.endsWith('.sh'))
+      : [];
+    console.log(chalk.gray(`  Hooks:      ${hooks.length > 0 ? chalk.green('✓') : chalk.red('✗')} (${hooks.length} 个)`));
+
+    // 4. 检查文档状态
+    console.log(chalk.white('\n文档状态：'));
+
+    const docsDir = path.join(cwd, 'docs');
+    const coreDir = path.join(docsDir, 'core');
+    const projectDir = path.join(docsDir, 'project');
+
+    if (await fs.pathExists(coreDir)) {
+      const coreDocs = (await fs.readdir(coreDir)).filter(f => f.endsWith('.md'));
+      console.log(chalk.gray(`  Core 文档:  ${coreDocs.length >= 4 ? chalk.green('✓') : chalk.yellow('⚠')} (${coreDocs.length}/4 个)`));
+    } else {
+      console.log(chalk.gray(`  Core 文档:  ${chalk.red('✗')} (未创建)`));
+    }
+
+    if (await fs.pathExists(projectDir)) {
+      const projectDocs = (await fs.readdir(projectDir))
+        .filter(f => f.endsWith('.md') && !f.endsWith('.example'));
+      console.log(chalk.gray(`  Project 文档: ${chalk.green('✓')} (${projectDocs.length} 个)`));
+    } else {
+      console.log(chalk.gray(`  Project 文档: ${chalk.gray('-')} (未创建)`));
+    }
+
+    console.log('');
+
+  } catch (error) {
+    console.error(chalk.red('\n❌ 读取状态失败：'), error.message);
+    process.exit(1);
+  }
+}
+
+module.exports = status;