npm - speccore - Versions diffs - 4.0.0 → 4.0.2 - Mend

speccore 4.0.0 → 4.0.2

This diff represents the content of publicly available package versions that have been released to one of the supported registries. The information contained in this diff is provided for informational purposes only and reflects changes between package versions as they appear in their respective public registries.

Files changed (3) hide show

package/README.en.md CHANGED Viewed

@@ -1,4 +1,4 @@
-# SpecCore
+# SpecCore CLI
 > **Code by Spec, Not by Vibe.**
@@ -6,389 +6,227 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)
-SpecCore is the official command-line tool for the [SpecCore](https://github.com/spec-core/spec-core) specification-driven development framework. It decouples deterministic operations (file creation, directory management, format validation, status statistics) from AI, executing them directly through code to improve efficiency and reduce Token consumption.
+SpecCore CLI is the official TypeScript command-line tool for the [SpecCore specification-driven development framework](https://github.com/windfallsheng/SpecCore). It decouples deterministic operations (file creation, directory management, format validation, status statistics) from AI, executing them directly through code to improve efficiency and reduce Token consumption.
----
-## One Minute Overview
-| Question | Answer |
-| :--- | :--- |
-| **What is this?** | CLI tool for SpecCore framework, deterministic operations executed by code, intelligent decisions handled by AI |
-| **What problem does it solve?** | AI file operations are error-prone, high Token consumption, context window waste |
-| **What do I need to install?** | Node.js >= 18, run `npm install -g speccore` |
-| **Relationship with Slash Commands?** | CLI is the underlying execution engine for Slash Commands, AI makes decisions, CLI executes |
+> 💡 **v4.0.0** | 39 Commands | 31 Intent Types | Multi-Platform
 ---
-## Feature Highlights
-- **🚀 Quick Initialization**: Initialize a complete SpecCore project structure with one command
-- **📁 Smart Directory Management**: Auto-create iterations, tasks, shared resource directories following specifications
-- **✅ Auto Compliance Check**: Scan all Spec files, check required fields and formats
-- **📊 Real-time Progress Tracking**: Auto-identify active iterations, calculate task completion rates
-- **🏥 Health Dashboard**: Evaluate project health with 4 dimensions and 12 metrics
-- **📈 One-click Reporting**: Support Markdown/HTML/JSON format output for project reports
-- **🧠 Context Awareness**: Auto-read `.speccore/local/context.json`, intelligently fill default values
-- **🔄 Deterministic Execution**: File operations, format validation, status statistics all executed locally with zero Token consumption
----
-## Design Philosophy
-SpecCore adopts an architecture that **decouples deterministic logic from intelligent logic**:
-| Logic Type | Responsibility | Executor | Example |
-| :--- | :--- | :--- | :--- |
-| **Deterministic Logic** | Structured operations | CLI code | Create directories, move files, parse YAML, validate formats, count status |
-| **Intelligent Logic** | Understanding & Decision | AI | Understand requirements, split tasks, generate code, review outputs |
-```
-User Input (Slash Command)
-        │
-        ▼
-┌───────────────────────────────────────┐
-│   AI Layer (Intelligent Decision)     │
-│   - Understand user intent            │
-│   - Decide which operations to execute│
-│   - Generate code content             │
-└───────────────────────────────────────┘
-        │ Call CLI Commands
-        ▼
-┌───────────────────────────────────────┐
-│   CLI Layer (Deterministic Execution) │
-│   - Create directory structure        │
-│   - Read/write files                  │
-│   - Parse YAML                        │
-│   - Validate formats                  │
-│   - Output JSON results               │
-└───────────────────────────────────────┘
-```
-**Core Benefit**: Directory checking, YAML parsing, and status statistics are executed deterministically by code. AI only interprets results and formats outputs, significantly reducing Token consumption.
+## 🧩 Two Ways to Use
----
+SpecCore has two distinct parts:
-## Requirements
+| | 🔧 Terminal (CLI) | 🤖 AI Commands (Slash) |
+| :--- | :--- | :--- |
+| **Where** | Terminal | AI coding tools (WorkBuddy / Cursor / Claude) |
+| **How** | `speccore init` | Type `/spec-xxx` |
+| **Mechanism** | TypeScript, direct file ops | Markdown prompts, AI reads & executes |
+| **Count** | 39 CLI commands | 39 Slash Commands |
+| **When** | Init, validation, batch ops | Daily dev: iteration, execution, review, archive |
-- **Node.js**: >= 18.0.0
-- **Operating System**: macOS / Linux / Windows
+> 💡 **Remember**: `speccore` prefix → Terminal; `/spec` prefix → AI tool.
 ---
-## Installation
+## 📦 Install
 ```bash
-# Global installation (recommended)
-npm install -g speccore
-# Or use npx (no installation required, always use latest version)
-npx speccore --version
-# Or install specific version
-npm install -g speccore@1.0.0
+npm install -g speccore          # Global install (recommended)
+npx speccore --version           # Or use npx
 ```
 ---
-## Quick Start
-### 1. Initialize Project
+## 🚀 Quick Start (5 min)
 ```bash
-# Enter your project directory
-cd my-project
+# 1. Initialize
+cd my-project && speccore init
-# Initialize SpecCore
-speccore init --mode fresh
+# 2. Import to global layer
+speccore import --project=user-service --path=./backend --type=backend
-# Or migrate existing project
-speccore init --mode migration
-```
+# 3. Create iteration
+speccore iteration create --name 2026-07-UserSystem
-After execution, the following structure will be generated:
+# 4. Multi-platform task
+speccore new-task --name UserLogin --platforms=web,h5
+# 5. Smart entry
+speccore spec "How's the progress?"
 ```
-.speccore/                          # Global configuration directory
-├── CONSTITUTION.md                 # Technical Constitution (tech stack, standards)
-├── SETTINGS.md                     # Framework configuration (switches, modes)
-├── ITERATIONS/                     # Iteration records
-├── PATTERNS/                       # Pattern library
-├── PROJECT/                        # Project-level assets
-│   ├── OVERVIEW.md
-│   ├── TEAM.md
-│   └── ...
-├── RULES/                          # Adjudication rules
-└── local/                          # Local state
-    └── context.json                # Current context (iteration, task, user)
-```
-### 2. Create Iteration
-```bash
-speccore iteration create --name 2026-07-User-System
-```
-Generates `Iteration-2026-07-User-System/` directory containing:
-- `00-Requirements/REQUIREMENT.md`
-- `00-Technical-Design/ARCHITECTURE.md`
-- `00-Iteration-Overview/PROJECT_GRAPH.md`
-### 3. Create Tasks
-```bash
-speccore task new --name User-Login --type feature
-speccore task new --name Phone-Registration --type feature
-speccore task new --name Password-Reset --type bugfix
-```
+> 📚 See [Quick Start Guide](docs/quick-start.en.md) for detailed steps.
-### 4. View Progress
+---
-```bash
-# View overall progress
-speccore progress
+## Feature Highlights
-# JSON format output (suitable for CI/CD)
-speccore progress --format json
+- **🚀 Quick Init**: One command initializes the full project structure, auto-integrates WorkBuddy
+- **📱 Multi-Platform**: `--platforms=web,h5,miniapp` per-platform Task management, dynamic platform types
+- **🧠 Intent Recognition**: 31 intent types, 200+ keywords, natural language → command matching
+- **🌐 Global Layer**: Cross-project requirement indexing via GLOBAL/ architecture
+- **📊 Progress Tracking**: Auto-detect active iteration, per-platform/per-assignee stats
+- **✅ Auto Compliance**: Scan all Spec files, check required fields and format
+- **🔄 Deterministic Execution**: File ops, validation, statistics — all local code, zero Token cost
-# View detailed progress
-speccore progress --detail
-```
+---
-### 5. Validate Compliance
+## Design Philosophy
-```bash
-# Validate all tasks
-speccore validate
+SpecCore decouples **deterministic logic from intelligent logic**:
-# Auto-fix fixable issues
-speccore validate --fix
+| Logic Type | Responsibility | Executor | Example |
+| :--- | :--- | :--- | :--- |
+| **Deterministic** | Structured operations | CLI code | Create dirs, parse YAML, validate, count |
+| **Intelligent** | Understanding & decision | AI tool | Understand requirements, split tasks, generate code |
-# JSON format output (AI can read directly)
-speccore validate --format json
 ```
-### 6. Generate Report
-```bash
-# Markdown format (default)
-speccore report
-# HTML format (suitable for email)
-speccore report --format html --output ./report.html
-# JSON format (suitable for import into other systems)
-speccore report --format json
-# Include team analysis and risk analysis
-speccore report --team --risk
+User Input (Natural Language / Slash Command)
+        │
+        ▼
+┌───────────────────────────────────────┐
+│   AI Layer (Intelligent Decision)     │
+│   - Understand user intent            │
+│   - Decide which operations to run    │
+│   - Generate code content             │
+└───────────────────────────────────────┘
+        │ Call CLI commands
+        ▼
+┌───────────────────────────────────────┐
+│   CLI Layer (Deterministic Execution) │
+│   - Create directory structure        │
+│   - Read/write config & Spec files    │
+│   - Parse YAML                        │
+│   - Compliance validation             │
+│   - Output structured results         │
+└───────────────────────────────────────┘
 ```
 ---
-## Full Command List
-### Initialization & Import
-| Command | Description | Corresponding Slash Command | Deterministic |
-| :--- | :--- | :--- | :--- |
-| `speccore init` | Initialize SpecCore project | `/spec-init` | ✅ |
-| `speccore import` | Import existing project | `/spec-import` | ✅ |
-### Iteration Management
-| Command | Description | Corresponding Slash Command | Deterministic |
-| :--- | :--- | :--- | :--- |
-| `speccore iteration create` | Create iteration | `/spec-iteration-create` | ✅ |
-| `speccore iteration split` | Requirement splitting (requires AI task list) | `/spec-iteration-split` | ⚠️ |
-### Task Management
-| Command | Description | Corresponding Slash Command | Deterministic |
-| :--- | :--- | :--- | :--- |
-| `speccore task new` | Create atomic task | `/spec-new-task` | ✅ |
-### Execution & Scheduling
+## 🔧 CLI Commands Quick Reference (39 total)
-| Command | Description | Corresponding Slash Command | Deterministic |
-| :--- | :--- | :--- | :--- |
-| `speccore plan` | Generate scheduling plan (DAG analysis) | `/spec-plan` | ✅ |
-| `speccore execute` | Execute task (requires AI collaboration) | `/spec-execute` | ⚠️ |
-### Validation & Review
-| Command | Description | Corresponding Slash Command | Deterministic |
-| :--- | :--- | :--- | :--- |
-| `speccore validate` | Compliance check | `/spec-validate` | ✅ |
-| `speccore progress` | View progress | `/spec-progress` | ✅ |
-| `speccore status` | Project status | `/spec-status` | ✅ |
-| `speccore health` | Health dashboard (4 dimensions, 12 metrics) | `/spec-health` | ✅ |
-| `speccore report` | Generate project report | `/spec-report` | ✅ |
-### Archive & Configuration
-| Command | Description | Corresponding Slash Command | Deterministic |
-| :--- | :--- | :--- | :--- |
-| `speccore archive` | Archive task | `/spec-archive` | ✅ |
-| `speccore config` | Configuration management | `/spec-config` | ✅ |
+> Run in terminal. All commands start with `speccore`.
-- **✅** Pure deterministic logic, fully executable by code
-- **⚠️** Requires AI participation for understanding/generation (e.g., requirement splitting, code generation)
+| Category | Key Commands |
+| :--- | :--- |
+| 🧠 Smart Entry | `speccore spec "<query>"` |
+| 🌐 Global Layer | `import` / `iteration-from-global` / `sync-global` / `global-status` / `history` / `index-update` |
+| 📋 Scenario | `goal` / `bugfix` / `research` / `retro` / `handover` |
+| 📐 Planning | `init` / `iteration create` / `iteration split` / `new-task` / `plan` |
+| ⚡ Execution | `execute` (--platform / --priority / --status) |
+| 🔄 Change | `change` / `sync` / `sync-global` |
+| ✅ Review | `validate` (--fix) |
+| 📊 Progress | `progress` (--platform / --detail) / `status` |
+| 📦 Management | `archive` / `config` / `baseline` / `rename` |
+| 🔗 Analysis | `impact` / `dashboard` / `audit` |
+| 📱 Platform | `platform-add` / `context` |
+| 🛠️ Tools | `health` / `report` / `template-add` / `help` / `demo` / `welcome` |
+## 🤖 AI Commands (Slash Command) Mapping
+> Type `/` in AI tools (WorkBuddy / Cursor / Claude Code etc.). AI commands call the corresponding CLI command internally.
+| CLI Command | AI Slash Command | Purpose |
+| :--- | :--- | :--- |
+| `speccore init` | `/spec-init` | Initialize project |
+| `speccore import` | `/spec-import` | Import to global layer |
+| `speccore iteration create` | `/spec-iteration-create` | Create iteration |
+| `speccore new-task` | `/spec-new-task` | Create multi-platform task |
+| `speccore execute` | `/spec-execute` | Execute development |
+| `speccore progress` | `/spec-progress` | View progress |
+| `speccore validate` | `/spec-validate` | Compliance check |
+| `speccore impact` | `/spec-impact` | Impact analysis |
+| `speccore audit` | `/spec-ai-audit` | AI smart audit |
+| `speccore spec "query"` | `/spec query` | Natural language intent |
+> 📋 Full command reference: [Command Reference](docs/commands.en.md) | 🧠 Intent mapping: [Intent Map](docs/commands.en.md#natural-language-intent-mapping-31-types)
 ---
-## Project Structure
+## 🏗️ Architecture
 ```
-speccore/
-├── package.json
-├── tsconfig.json
-├── README.md
-├── bin/
-│   └── speccore                    # CLI entry script
-├── src/
-│   ├── index.ts                    # Entry file
-│   ├── cli.ts                      # CLI command registration (Commander.js)
-│   │
-│   ├── commands/                   # All CLI command implementations
-│   │   ├── init.ts                 # Initialize project
-│   │   ├── import.ts               # Import existing project
-│   │   ├── iteration/
-│   │   │   ├── create.ts           # Create iteration
-│   │   │   └── split.ts            # Requirement splitting
-│   │   ├── task/
-│   │   │   └── new.ts              # Create task
-│   │   ├── plan.ts                 # Generate scheduling plan
-│   │   ├── execute.ts              # Execute task
-│   │   ├── validate.ts             # Compliance check
-│   │   ├── archive.ts              # Archive task
-│   │   ├── progress.ts             # View progress
-│   │   ├── status.ts               # Project status
-│   │   ├── health.ts               # Health dashboard
-│   │   ├── report.ts               # Generate report
-│   │   └── config.ts               # Configuration management
-│   │
-│   ├── core/                       # Core engine
-│   │   ├── context.ts              # Context management (read context.json)
-│   │   ├── state.ts                # State management (read PROJECT_GRAPH.md)
-│   │   ├── yaml-parser.ts          # YAML parsing
-│   │   ├── template-engine.ts      # Template rendering (Handlebars)
-│   │   └── validator.ts            # Compliance check engine
-│   │
-│   ├── templates/                  # Built-in templates
-│   │   ├── spec/                   # Spec file templates
-│   │   │   └── project-readme.md
-│   │   └── code/                   # Code generation templates
-│   │       ├── spring-controller.java
-│   │       ├── spring-service.java
-│   │       ├── spring-test.java
-│   │       └── nest-controller.ts
-│   │
-│   └── utils/
-│       ├── file.ts                 # File utilities
-│       ├── git.ts                  # Git utilities (get username, etc.)
-│       └── logger.ts               # Logger (with progress bar, Spinner)
-│
-└── dist/                           # Compiled output (TypeScript → JavaScript)
+.speccore/GLOBAL/   ← Global Layer: unified multi-project requirements
+.speccore/           ← Project Layer: constitution, config, patterns
+Iteration-XXX/       ← Iteration Layer: what this iteration does
+  └── Task-XXX/      ← Task Layer: how this feature works
+      ├── _shared/   ← Shared: API Contract + business rules
+      ├── backend/   ← Backend Specs
+      └── frontend/  ← Multi-platform frontend specs (web / h5 / miniapp)
 ```
 ---
-## Development Guide
-```bash
-# Clone repository
-git clone https://github.com/windfallsheng/SpecCore-ts.git
-cd SpecCore-ts
-# Install dependencies
-npm install
-# Compile TypeScript
-npm run build
+## 🛠️ Tool Support
-# Development mode (watch for file changes and auto-compile)
-npm run watch
+| CN | Global |
+| :--- | :--- |
+| WorkBuddy / Qcoder / Trae | Cursor / Claude Code / Windsurf / Gemini CLI / OpenCode |
-# Local testing
-node bin/speccore --version
+SpecCore CLI natively integrates WorkBuddy. Other tools supported via the SpecCore framework.
-# Link to global (development testing)
-npm link
-speccore --version
-```
+> 📚 See [Tool Adaptation](docs/tool-adaptation.en.md)
 ---
-## Related Projects
+## 📚 Documentation
-| Project | Description | GitHub | Gitee |
-| :--- | :--- | :--- | :--- |
-| **SpecCore** | Specification-driven development framework (methodology + file templates + Slash Commands) | [windfallsheng/SpecCore](https://github.com/windfallsheng/SpecCore) | [windfullsheng/spec-core](https://gitee.com/windfullsheng/spec-core) |
-| **SpecCore** | CLI tool (deterministic operation execution engine) | [windfallsheng/SpecCore-ts](https://github.com/windfallsheng/SpecCore-ts) | [windfullsheng/spec-core-ts](https://gitee.com/windfullsheng/spec-core-ts) |
+| Document | Lang | Content |
+| :--- | :--- | :--- |
+| [Quick Start](docs/quick-start.en.md) | 🇬🇧 | Install → Init → Import → Multi-platform → Scenarios |
+| [快速开始指南](docs/快速开始.md) | 🇨🇳 | 安装 → 初始化 → 导入 → 多端 Task → 场景速查 |
+| [Command Reference](docs/commands.en.md) | 🇬🇧 | 39 commands full params + 31 intents + aliases |
+| [命令参考手册](docs/命令参考.md) | 🇨🇳 | 39 个命令完整参数 + 31 种意图映射 + 别名速查 |
+| [Tool Adaptation](docs/tool-adaptation.en.md) | 🇬🇧 | WorkBuddy integration + workflow + security |
+| [工具适配说明](docs/工具适配说明.md) | 🇨🇳 | WorkBuddy 集成原理 + 工作流程 + 安全检查 |
+| [CHANGELOG](CHANGELOG.md) | 🇨🇳 | Version history (v1.0.0 → v4.0.0) |
+| [README.md](README.md) | 🇨🇳 | 中文项目概述 |
 ---
 ## FAQ
-### Q: Command not found after installation?
-A: Ensure npm global bin directory is in PATH:
-```bash
-# Check global installation path
-npm bin -g
-# Add to PATH (macOS/Linux)
-export PATH="$(npm bin -g):$PATH"
-```
-### Q: How to update to latest version?
-```bash
-npm update -g speccore
-```
-### Q: How to uninstall?
-```bash
-npm uninstall -g speccore
-```
+| Q | A |
+| :--- | :--- |
+| **Command not found?** | Add npm bin to PATH: `export PATH="$(npm bin -g):$PATH"` |
+| **How to update?** | `npm update -g speccore` |
+| **Same feature on Web+H5+MiniApp?** | `speccore new-task --platforms=web,h5,miniapp` |
+| **Add new platform?** | `speccore platform-add --name=tablet --tech="React Native"` |
+| **Rename iteration/task?** | `speccore rename --target=old --new-name=new` |
+| **Batch rename?** | `speccore rename --batch --pattern="Task-" --replacement="Feature-"` |
+| **Rebuild requirement index?** | `speccore index-update` (--dry-run to preview) |
-### Q: How to integrate with AI tools?
+---
-A: AI tools (like WorkBuddy) execute deterministic operations by calling CLI commands. For example:
+## Development
 ```bash
-# When AI executes /spec-validate, it internally calls:
-speccore validate --json
-# AI reads JSON results and generates user-friendly reports
+git clone https://github.com/windfallsheng/SpecCore-ts.git
+cd SpecCore-ts/ts-cli
+npm install && npm run build
+npm run watch           # Dev mode
+npm link && speccore --version   # Local test
+bash verify.sh          # Run tests
 ```
 ---
-## Contributing
-Welcome to submit Issues and Pull Requests!
+## Related Projects
-1. Fork this repository
-2. Create feature branch: `git checkout -b feature/my-feature`
-3. Commit changes: `git commit -m 'feat: add some feature'`
-4. Push branch: `git push origin feature/my-feature`
-5. Create Pull Request
+| Project | Description | Link |
+| :--- | :--- | :--- |
+| **SpecCore Framework** | Spec-driven methodology + Slash Commands + templates | [GitHub](https://github.com/windfallsheng/SpecCore) |
+| **SpecCore CLI** | TypeScript CLI tool (deterministic execution engine) | [GitHub](https://github.com/windfallsheng/SpecCore-ts) |
 ---
-## Changelog
+## Version
-### v1.0.0 (2026-07-05)
+v4.0.0 | 🔧 CLI Commands: 39 | 🧠 Intents: 31
-- Initial release
-- Supports 14 CLI commands
-- Core engine: context management, state management, YAML parsing, template rendering, compliance checking
-- Built-in templates: Spring Boot Controller/Service/Test, NestJS Controller
-- Support JSON/Markdown/HTML multi-format output
+Changelog: [CHANGELOG.md](CHANGELOG.md)
 ---
@@ -398,4 +236,4 @@ Welcome to submit Issues and Pull Requests!
 ---
-<p align="center">Built with ❤️ by the SpecCore Team</p>
+<p align="center">Built with ❤️ by the SpecCore Team</p>

package/README.md CHANGED Viewed

@@ -1,4 +1,4 @@
-# SpecCore
+# SpecCore CLI
 > **Code by Spec, Not by Vibe.**
@@ -6,34 +6,68 @@
 [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
 [![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)
-SpecCore 是 [SpecCore](https://github.com/spec-core/spec-core) 规范驱动开发框架的官方命令行工具。它将确定性操作（文件创建、目录管理、格式校验、状态统计）从 AI 中剥离，由代码直接执行，提升效率并降低 Token 消耗。
+SpecCore CLI 是 [SpecCore 规范驱动开发框架](https://github.com/windfallsheng/SpecCore) 的官方 TypeScript 命令行工具。它将确定性操作（文件创建、目录管理、格式校验、状态统计）从 AI 中剥离，由代码直接执行，提升效率并降低 Token 消耗。
 ---
-## 一分钟了解
+## 🧩 两种使用方式
-| 问题 | 答案 |
-| :--- | :--- |
-| **这是什么？** | SpecCore 框架的 CLI 工具，确定性操作由代码执行，智能决策由 AI 负责 |
-| **解决什么问题？** | AI 做文件操作容易出错、Token 消耗高、上下文窗口浪费 |
-| **需要安装什么？** | Node.js >= 18，执行 `npm install -g speccore` |
-| **和 Slash Command 的关系？** | CLI 是 Slash Command 的底层执行引擎，AI 负责决策，CLI 负责执行 |
+SpecCore 由两部分组成，**职责明确，互不混淆**：
+| | 🔧 终端命令（CLI） | 🤖 AI 命令（Slash Command） |
+| :--- | :--- | :--- |
+| **在哪里执行** | 终端 / Terminal | AI 编程工具（WorkBuddy / Cursor / Claude 等） |
+| **怎么用** | `speccore init` | 输入 `/spec-xxx` |
+| **什么原理** | TypeScript 编译，直接操作文件 | Markdown 指令，AI 读取后执行 |
+| **数量** | 39 个 CLI 命令 | 39 个 Slash Command |
+| **何时用** | 项目初始化、文件校验、批量操作 | 日常开发：需求管理、开发执行、审查归档 |
+> 💡 **简单记忆**：`speccore` 开头 → 终端执行；`/spec` 开头 → AI 工具中执行。
+---
+## 📦 安装
+```bash
+npm install -g speccore          # 全局安装（推荐）
+npx speccore --version           # 或使用 npx
+```
+---
+## 🚀 快速开始（5 分钟）
+```bash
+# 1. 初始化项目
+cd my-project && speccore init
+# 2. 导入项目到全量层
+speccore import --project=user-service --path=./backend --type=backend
+# 3. 创建期次
+speccore iteration create --name 2026-07-用户系统
+# 4. 创建多平台 Task
+speccore new-task --name 用户登录 --platforms=web,h5
+# 5. 自然语言入口
+speccore spec "进度怎么样了"
+```
+> 📚 更多场景和详细步骤见 [快速开始指南](docs/快速开始.md)
 ---
 ## 特性亮点
-- **🚀 快速初始化**：一行命令初始化完整的 SpecCore 项目结构
-- **📁 智能目录管理**：自动创建期次、任务、共享资源目录，符合规范
+- **🚀 快速初始化**：一行命令初始化完整 SpecCore 项目结构，自动集成 WorkBuddy
+- **📱 多平台支持**：`--platforms=web,h5,miniapp` 按端管理 Task，动态添加平台类型
+- **🧠 意图识别引擎**：31 种意图类型，200+ 关键词，自然语言自动匹配命令
+- **🌐 多项目全量层**：GLOBAL/ 统一管理跨项目需求索引、架构和技术栈
+- **📊 实时进度追踪**：自动识别活跃期次，统计任务完成率，按平台/人员/类型统计
 - **✅ 自动合规检查**：扫描所有 Spec 文件，检查必填项和格式
-- **📊 实时进度追踪**：自动识别活跃期次，统计任务完成率
-- **🏥 健康度看板**：4 维度 12 指标评估项目健康状态
-- **📈 一键报告**：支持 Markdown/HTML/JSON 格式输出项目报告
-- **🧠 意图识别引擎**：23 种意图类型，200+ 关键词匹配，自然语言→命令自动匹配
-- **🧠 上下文感知**：自动读取 `.speccore/local/context.json`，智能填充默认值
+- **🏥 项目健康度**：4 维度 12 指标评估项目健康状态
 - **🔄 确定性执行**：文件操作、格式校验、状态统计全部本地代码执行，零 Token 消耗
-- **🌐 多项目全量层**：GLOBAL/ 目录管理跨项目需求索引、架构、技术栈
-- **📱 多平台支持**：Web/H5/小程序多端 Task 管理，平台动态添加
 ---
@@ -43,15 +77,15 @@ SpecCore 采用**确定性逻辑与智能逻辑解耦**的架构：
 | 逻辑类型 | 职责 | 执行方 | 示例 |
 | :--- | :--- | :--- | :--- |
-| **确定性逻辑** | 结构化操作 | CLI 代码 | 创建目录、移动文件、解析 YAML、校验格式、统计状态 |
-| **智能逻辑** | 理解与决策 | AI | 理解需求、拆分任务、生成代码、审查产出 |
+| **确定性逻辑** | 结构化操作 | CLI 代码 | 创建目录、读写文件、解析 YAML、校验格式、统计状态 |
+| **智能逻辑** | 理解与决策 | AI 工具 | 理解需求、拆分任务、生成代码、审查产出 |
 ```
-用户输入 (Slash Command)
+用户输入（自然语言 / Slash Command）
         │
         ▼
 ┌───────────────────────────────────────┐
-│   AI 层 (智能决策)                     │
+│   AI 层（智能决策）                     │
 │   - 理解用户意图                       │
 │   - 决定执行哪些操作                   │
 │   - 生成代码内容                       │
@@ -59,293 +93,112 @@ SpecCore 采用**确定性逻辑与智能逻辑解耦**的架构：
         │ 调用 CLI 命令
         ▼
 ┌───────────────────────────────────────┐
-│   CLI 层 (确定性执行)                  │
+│   CLI 层（确定性执行）                  │
 │   - 创建目录结构                       │
-│   - 读写文件                           │
+│   - 读写配置和 Spec 文件               │
 │   - 解析 YAML                          │
-│   - 校验格式                           │
-│   - 输出 JSON 结果                     │
+│   - 合规校验                           │
+│   - 输出结构化结果（JSON/Markdown）      │
 └───────────────────────────────────────┘
 ```
-**核心收益**：目录检查、YAML 解析、状态统计由代码确定执行，AI 只负责"解读结果"和"格式化输出"，Token 消耗大幅降低。
 ---
-## 环境要求
-- **Node.js**: >= 18.0.0
-- **操作系统**: macOS / Linux / Windows
+## 🔧 终端命令速查（39 个 CLI 命令）
+> 在终端中执行，所有命令以 `speccore` 开头。
+| 分类 | 命令 | 说明 |
+| :--- | :--- | :--- |
+| 🧠 智能入口 | `speccore spec "<query>"` | 自然语言意图识别 |
+| 🌐 初始化/导入 | `speccore init` / `import` | 项目初始化 + 多项目导入 |
+| 📐 计划 | `speccore iteration create/split` / `new-task` / `plan` | 期次管理 + Task 创建 |
+| | `speccore iteration-from-global` | 从全量层生成期次 |
+| ⚡ 执行 | `speccore execute` | 执行控制中心（--platform / --priority） |
+| 🔄 变更 | `speccore change` / `sync` / `sync-global` | 需求变更 + 反向同步 + 全量同步 |
+| ✅ 审查 | `speccore validate` | 合规性检查（--fix） |
+| 📊 进度 | `speccore progress` / `status` | 进度总览（--platform / --detail） |
+| 🔬 分析 | `speccore impact` / `baseline` / `dashboard` / `audit` | 影响分析 + 基线 + 仪表盘 + 审计 |
+| 🌐 全量层 | `speccore global-status` / `history` / `index-update` | 全量状态 + 历史 + 索引更新 |
+| 📱 平台 | `speccore platform-add` / `context` | 动态平台 + 上下文查看 |
+| 🎯 场景 | `speccore goal` / `bugfix` / `research` / `handover` / `retro` | 端到端需求 + Bug + 调研 + 交接 + 回顾 |
+| 🛠️ 工具 | `speccore health` / `report` / `archive` / `config` / `rename` / `template-add` / `help` / `demo` / `welcome` | 健康度 + 报告 + 归档 + 配置 + 重命名等 |
+## 🤖 AI 命令（Slash Command）对应关系
+> 在 AI 工具（WorkBuddy / Cursor / Claude Code 等）中输入 `/` + 命令。AI 命令在底层调用对应的 CLI 命令执行。
+| CLI 终端命令 | AI Slash Command | 用途 |
+| :--- | :--- | :--- |
+| `speccore init` | `/spec-init` | 项目初始化 |
+| `speccore import` | `/spec-import` | 导入项目到全量层 |
+| `speccore iteration create` | `/spec-iteration-create` | 创建期次 |
+| `speccore new-task` | `/spec-new-task` | 创建多平台 Task |
+| `speccore execute` | `/spec-execute` | 执行开发任务 |
+| `speccore progress` | `/spec-progress` | 查看进度 |
+| `speccore validate` | `/spec-validate` | 合规性检查 |
+| `speccore impact` | `/spec-impact` | 变更影响分析 |
+| `speccore audit` | `/spec-ai-audit` | AI 智能审计 |
+| `speccore spec "查询"` | `/spec 查询` | 自然语言智能入口 |
+> 📋 完整命令参数见 [命令参考手册](docs/命令参考.md) | 🧠 31 种意图映射见 [意图映射表](docs/命令参考.md#自然语言意图映射31-种)
 ---
-## 安装
-```bash
-# 全局安装（推荐）
-npm install -g speccore
-# 或使用 npx（无需安装，每次使用最新版）
-npx speccore --version
+## 🏗️ 架构
-# 或安装指定版本
-npm install -g speccore@1.0.0
 ```
----
-## 快速开始
-### 1. 初始化项目
-```bash
-# 进入你的项目目录
-cd my-project
-# 初始化 SpecCore
-speccore init --mode fresh
-# 或迁移现有项目
-speccore init --mode migration
-```
-执行后，当前目录会生成：
-```
-.speccore/                          # 全局配置目录
-├── CONSTITUTION.md                 # 技术宪法（定义技术栈、规范）
-├── SETTINGS.md                     # 框架配置（开关、模式）
-├── ITERATIONS/                     # 期次记录
-├── PATTERNS/                       # 模式库
-├── PROJECT/                        # 项目级资产
-│   ├── OVERVIEW.md
-│   ├── TEAM.md
-│   └── ...
-├── RULES/                          # 裁决规则
-└── local/                          # 本地状态
-    └── context.json                # 当前上下文（期次、任务、用户）
-```
-### 2. 创建期次
-```bash
-speccore iteration create --name 2026-07-用户系统
-```
-生成 `期次-2026-07-用户系统/` 目录，包含：
-- `00-需求文档/REQUIREMENT.md`
-- `00-技术文档/ARCHITECTURE.md`
-- `00-期次总览/PROJECT_GRAPH.md`
-### 3. 创建任务
-```bash
-speccore task new --name 用户登录 --type feature
-speccore task new --name 手机号注册 --type feature
-speccore task new --name 密码重置 --type bugfix
-```
-### 4. 查看进度
-```bash
-# 查看整体进度
-speccore progress
-# JSON 格式输出（适合 CI/CD）
-speccore progress --format json
-# 查看详细进度
-speccore progress --detail
-```
-### 5. 验证合规性
-```bash
-# 验证所有任务
-speccore validate
-# 自动修复可修复的问题
-speccore validate --fix
-# JSON 格式输出（AI 可直接读取）
-speccore validate --format json
-```
-### 6. 生成报告
-```bash
-# Markdown 格式（默认）
-speccore report
-# HTML 格式（适合邮件发送）
-speccore report --format html --output ./report.html
-# JSON 格式（适合导入其他系统）
-speccore report --format json
-# 包含团队分析和风险分析
-speccore report --team --risk
+.speccore/GLOBAL/   ← 全量层：多项目统一需求管理
+.speccore/           ← 全局层：项目宪法、配置、模式
+期次-XXX/            ← 期次层：这一期做什么
+  └── Task-XXX/      ← 任务层：这个功能怎么做
+      ├── _shared/   ← 共享层：API Contract + 业务规则
+      ├── backend/   ← 后端 Spec
+      └── frontend/  ← 前端多端 Spec（web / h5 / miniapp）
 ```
 ---
-## 完整命令列表
-### 初始化与导入
+## 🛠️ 工具适配
-| 命令 | 别名 | 说明 | 确定性 |
-| :--- | :--- | :--- | :--- |
-| `speccore init` | `in` | 初始化 SpecCore 项目（含 WorkBuddy 集成） | ✅ |
-| `speccore import` | `imp` | 导入项目到全量层（支持 --scope/--ignore/--update） | ✅ |
-### 智能入口
-| 命令 | 别名 | 说明 | 确定性 |
-| :--- | :--- | :--- | :--- |
-| `speccore spec "<query>"` | — | 自然语言意图识别，自动匹配命令 | ⚠️ |
-### 期次管理
-| 命令 | 别名 | 说明 | 确定性 |
-| :--- | :--- | :--- | :--- |
-| `speccore iteration create` | `it cr` | 创建期次 | ✅ |
-| `speccore iteration split` | `it sp` | 需求拆分 | ⚠️ |
-| `speccore iteration-from-global` | `ifg` | 从全量层生成期次 | ⚠️ |
-### 任务管理 (v4.0 增强)
-| 命令 | 别名 | 说明 | 确定性 |
-| :--- | :--- | :--- | :--- |
-| `speccore new-task` | `nt` | 创建多平台原子任务（--platforms） | ✅ |
-| `speccore task new` | `ch nt-` | 创建传统单任务 | ✅ |
-### 执行与调度 (v4.0 增强)
-| 命令 | 别名 | 说明 | 确定性 |
-| :--- | :--- | :--- | :--- |
-| `speccore plan` | `pl` | 生成调度方案（DAG 分析） | ✅ |
-| `speccore execute` | `ex` | 执行任务（支持 --platform/--priority/--status） | ⚠️ |
-### 变更与同步
-| 命令 | 别名 | 说明 | 确定性 |
-| :--- | :--- | :--- | :--- |
-| `speccore change` | `cg` | 需求变更联动 | ⚠️ |
-| `speccore sync` | `sy` | 代码→Spec 反向同步 | ⚠️ |
-| `speccore sync-global` | `sg` | 期次↔全量层双向同步 | ✅ |
-### 验证与审查
-| 命令 | 别名 | 说明 | 确定性 |
-| :--- | :--- | :--- | :--- |
-| `speccore validate` | `rv` | 合规性检查 | ✅ |
-| `speccore progress` | `pg` | 进度查看（支持 --platform） | ✅ |
-| `speccore status` | `st` | 项目状态 | ✅ |
-| `speccore health` | `hl` | 健康度看板（4维度12指标） | ✅ |
-| `speccore report` | `rp` | 生成项目报告 | ✅ |
-### 分析审计
-| 命令 | 别名 | 说明 | 确定性 |
-| :--- | :--- | :--- | :--- |
-| `speccore impact` | `if` | 变更影响分析 | ⚠️ |
-| `speccore baseline` | `bl` | 版本基线管理 | ✅ |
-| `speccore dashboard` | `db` | 可视化仪表盘（Chart.js HTML） | ✅ |
-| `speccore audit` | `ad` | AI 智能审计 | ⚠️ |
-### 全量层管理
+| 国内 | 国际 |
+| :--- | :--- |
+| WorkBuddy / Qcoder / Trae | Cursor / Claude Code / Windsurf / Gemini CLI / OpenCode |
-| 命令 | 别名 | 说明 | 确定性 |
-| :--- | :--- | :--- | :--- |
-| `speccore global-status` | `gs` | 全量层状态总览 | ✅ |
-| `speccore history` | `hs` | 需求变更历史 | ✅ |
-| `speccore index-update` | `iu` | 扫描需求重建 GLOBAL/INDEX | ✅ |
+SpecCore CLI 原生集成 WorkBuddy（`speccore init` 自动创建 `.workbuddy/` skill 和 memory）。其他工具通过 SpecCore 源项目适配。
-### 工具与场景 (v4.0 新增)
+> 📚 完整适配说明见 [工具适配说明](docs/工具适配说明.md)
-| 命令 | 别名 | 说明 | 确定性 |
-| :--- | :--- | :--- | :--- |
-| `speccore goal` | — | 完整需求交付（需求→代码全流程） | ⚠️ |
-| `speccore bugfix` | `bf` | 快速 Bug 修复 | ⚠️ |
-| `speccore research` | `rs` | 技术调研 | ⚠️ |
-| `speccore handover` | `ho` | 交接文档生成 | ✅ |
-| `speccore retro` | `rt` | 期次回顾总结 | ⚠️ |
-| `speccore rename` | `rn` | 重命名期次/任务（自动更新引用） | ✅ |
-| `speccore platform-add` | `padd` | 动态添加前端平台类型 | ✅ |
-| `speccore context` | `ctx` | 查看 Task 上下文和依赖链 | ✅ |
-### 辅助命令
-| 命令 | 别名 | 说明 | 确定性 |
-| :--- | :--- | :--- | :--- |
-| `speccore template-add` | `ta` | 添加代码模板 | ✅ |
-| `speccore archive` | `ar` | 归档任务 | ✅ |
-| `speccore config` | `cf` | 配置管理 | ✅ |
-| `speccore help` | `hp` | 命令帮助 | ✅ |
-| `speccore demo` | `dm` | 快速体验 | ✅ |
-| `speccore welcome` | `wc` | 首次使用引导 | ✅ |
+---
-- **✅** 纯确定性逻辑，可完全由代码执行
-- **⚠️** 需要 AI 参与理解/生成
+## 📚 文档
-> **命令总数：39 个**（v4.0.0）
+| 文档 | 语言 | 内容 |
+| :--- | :--- | :--- |
+| [快速开始指南](docs/快速开始.md) | 🇨🇳 | 安装 → 初始化 → 导入 → 多端 Task → 场景速查 |
+| [Quick Start](docs/quick-start.en.md) | 🇬🇧 | Install → Init → Import → Multi-platform → Scenarios |
+| [命令参考手册](docs/命令参考.md) | 🇨🇳 | 39 个命令完整参数 + 31 种意图映射 + 别名速查 |
+| [Command Reference](docs/commands.en.md) | 🇬🇧 | 39 commands full params + 31 intents + aliases |
+| [工具适配说明](docs/工具适配说明.md) | 🇨🇳 | WorkBuddy 集成原理 + 工作流程 + 安全检查 |
+| [Tool Adaptation](docs/tool-adaptation.en.md) | 🇬🇧 | WorkBuddy integration + workflow + security |
+| [CHANGELOG](CHANGELOG.md) | 🇨🇳 | 版本历史与更新日志（v1.0.0 → v4.0.0） |
+| [README.en.md](README.en.md) | 🇬🇧 | English project overview |
 ---
-## 项目结构
+## 常见问题
-```
-speccore/
-├── package.json
-├── tsconfig.json
-├── README.md
-├── bin/
-│   └── speccore                    # CLI 入口脚本
-├── src/
-│   ├── index.ts                    # 入口文件
-│   ├── cli.ts                      # CLI 命令注册（Commander.js）
-│   │
-│   ├── commands/                   # 所有 CLI 命令实现
-│   │   ├── init.ts                 # 初始化项目
-│   │   ├── import.ts               # 导入现有项目
-│   │   ├── iteration/
-│   │   │   ├── create.ts           # 创建期次
-│   │   │   └── split.ts            # 需求拆分
-│   │   ├── task/
-│   │   │   └── new.ts              # 创建任务
-│   │   ├── plan.ts                 # 生成调度方案
-│   │   ├── execute.ts              # 执行任务
-│   │   ├── validate.ts             # 合规性检查
-│   │   ├── archive.ts              # 归档任务
-│   │   ├── progress.ts             # 进度查看
-│   │   ├── status.ts               # 项目状态
-│   │   ├── health.ts               # 健康度看板
-│   │   ├── report.ts               # 生成报告
-│   │   └── config.ts               # 配置管理
-│   │
-│   ├── core/                       # 核心引擎
-│   │   ├── context.ts              # 上下文管理（读取 context.json）
-│   │   ├── state.ts                # 状态管理（读取 PROJECT_GRAPH.md）
-│   │   ├── yaml-parser.ts          # YAML 解析
-│   │   ├── template-engine.ts      # 模板渲染（Handlebars）
-│   │   └── validator.ts            # 合规性检查引擎
-│   │
-│   ├── templates/                  # 内置模板
-│   │   ├── spec/                   # Spec 文件模板
-│   │   │   └── project-readme.md
-│   │   └── code/                   # 代码生成模板
-│   │       ├── spring-controller.java
-│   │       ├── spring-service.java
-│   │       ├── spring-test.java
-│   │       └── nest-controller.ts
-│   │
-│   └── utils/
-│       ├── file.ts                 # 文件工具
-│       ├── git.ts                  # Git 工具（获取用户名等）
-│       └── logger.ts               # 日志输出（含进度条、Spinner）
-│
-└── dist/                           # 编译输出（TypeScript → JavaScript）
-```
+| 问题 | 答案 |
+| :--- | :--- |
+| **安装后命令找不到？** | 确保 npm bin 目录在 PATH 中：`export PATH="$(npm bin -g):$PATH"` |
+| **如何更新？** | `npm update -g speccore` |
+| **同一个功能多端怎么管理？** | `speccore new-task --platforms=web,h5,miniapp`，按端执行和统计 |
+| **如何添加新平台？** | `speccore platform-add --name=tablet --tech="React Native"` |
+| **期次/Task 想改名？** | `speccore rename --target=旧名 --new-name=新名` |
+| **批量重命名？** | `speccore rename --batch --pattern="Task-" --replacement="Feature-"` |
+| **手动改了文档，需要同步？** | `speccore sync --task=Task-001` 或 `speccore sync-global` |
+| **需求编号重复？** | `speccore validate --fix` 自动检测修复 |
+| **如何重建需求索引？** | `speccore index-update`（--dry-run 预览） |
 ---
@@ -353,73 +206,38 @@ speccore/
 ```bash
 # 克隆仓库
-git clone https://github.com/spec-core/speccore.git
-cd speccore
+git clone https://github.com/windfallsheng/SpecCore-ts.git
+cd SpecCore-ts/ts-cli
-# 安装依赖
-npm install
+# 安装依赖 + 编译
+npm install && npm run build
-# 编译 TypeScript
-npm run build
-# 开发模式（监听文件变化自动编译）
+# 开发模式
 npm run watch
 # 本地测试
-node bin/speccore --version
+npm link && speccore --version
-# 链接到全局（开发测试）
-npm link
-speccore --version
+# 运行验证脚本
+bash verify.sh
 ```
 ---
-## 常见问题
-### Q: 安装后命令找不到？
-A: 确保 npm 全局 bin 目录在 PATH 中：
-```bash
-# 查看全局安装路径
-npm bin -g
-# 添加到 PATH（macOS/Linux）
-export PATH="$(npm bin -g):$PATH"
-```
-### Q: 如何更新到最新版本？
-```bash
-npm update -g speccore
-```
-### Q: 如何卸载？
-```bash
-npm uninstall -g speccore
-```
-### Q: 与 AI 工具如何配合？
-A: AI 工具（如 WorkBuddy）通过调用 CLI 命令来执行确定性操作。例如：
-```bash
-# AI 执行 /spec-validate 时，内部调用：
-speccore validate --json
+## 相关项目
-# AI 读取 JSON 结果，生成用户友好的中文报告
-```
+| 项目 | 说明 | 链接 |
+| :--- | :--- | :--- |
+| **SpecCore 框架** | 规范驱动开发方法论 + Slash Commands + 模板 | [GitHub](https://github.com/windfallsheng/SpecCore) |
+| **SpecCore CLI** | TypeScript CLI 工具（确定性操作执行引擎） | [GitHub](https://github.com/windfallsheng/SpecCore-ts) |
 ---
-## 相关项目
+## 版本
-| 项目 | 说明 | GitHub | Gitee |
-| :--- | :--- | :--- | :--- |
-| **SpecCore** | 规范驱动开发框架（方法论 + 文件模板 + Slash Commands） | [windfallsheng/SpecCore](https://github.com/windfallsheng/SpecCore) | [windfullsheng/spec-core](https://gitee.com/windfullsheng/spec-core) |
-| **SpecCore** | CLI 工具（确定性操作执行引擎） | [windfallsheng/SpecCore-ts](https://github.com/windfallsheng/SpecCore-ts) | [windfullsheng/spec-core-ts](https://gitee.com/windfullsheng/spec-core-ts) |
+v4.0.0 | 🔧 CLI 命令 39 个 | 🧠 意图识别 31 种
+版本历史见 [CHANGELOG.md](CHANGELOG.md)
 ---
@@ -435,41 +253,6 @@ speccore validate --json
 ---
-## 更新日志
-### v4.0.0 (2026-07-09) — 最新
-- 🆕 **新增命令**：`new-task`（多平台任务创建）、`platform-add`（动态添加平台）、`index-update`（重建全量索引）、`context`（上下文查看）
-- 📱 **多平台支持**：.speccore/config/platforms.yaml 平台配置，Task 目录支持 frontend/{web,h5,miniapp}/
-- 🔧 **命令增强**：`execute` 增加 --platform；`progress` 增加 --platform；`import` 增加 --scope/--ignore/--update
-- 🧠 **意图识别升级**：31 种意图类型（新增 new_task/platform_add/index_update/context）
-- 🤖 **WorkBuddy 集成**：`speccore init` 自动创建 .workbuddy/ skill 和 memory 文件
-- 📋 **命令总数**：39 个（原 35 + 新增 4）
-### v3.0.0 (2026-07-05)
-- 🌐 **多项目全量层**：GLOBAL/ 目录管理跨项目需求索引、架构、技术栈
-- 🔗 **全链路可追溯**：需求→Task→代码双向追踪
-- 📊 **P0/P1/P2 命令**：impact（影响分析）、baseline（基线管理）、dashboard（仪表盘）、audit（智能审计）
-- ✏️ **rename 命令**：重命名期次/任务自动更新引用
-- 📋 **命令总数**：35 个（原 26 + 新增 4 + rename + 全量层）
-### v2.0.0 (2026-07-05)
-- 🧠 **意图识别引擎**：12 种意图类型、100+ 关键词匹配
-- 🚀 **新增命令**：spec（智能入口）、goal、bugfix、research、change、sync、handover、retro、template-add、help、demo、welcome
-- 📋 **命令总数**：26 个
-### v1.0.0 (2026-07-05)
-- 🎉 初始版本发布
-- 支持 14 个 CLI 命令
-- 核心引擎：上下文管理、状态管理、YAML 解析、模板渲染、合规检查
-- 内置模板：Spring Boot Controller/Service/Test、NestJS Controller
-- 支持 JSON/Markdown/HTML 多格式输出
----
 ## License
 [MIT](https://opensource.org/licenses/MIT)

package/package.json CHANGED Viewed

@@ -1,6 +1,6 @@
 {
   "name": "speccore",
-  "version": "4.0.0",
+  "version": "4.0.2",
   "description": "SpecCore - Code by Spec, Not by Vibe.",
   "main": "dist/index.js",
   "types": "dist/index.d.ts",