speccore 1.0.1 → 4.0.1

package/README.en.md

@@ -1,4 +1,4 @@
-# SpecCore
+# SpecCore CLI
 
 > **Code by Spec, Not by Vibe.**
 
@@ -6,389 +6,208 @@
 [![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
-
-| 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` | ✅ |
+## 🤖 Command Quick Reference (39 total)
 
-- **✅** 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` |
+
+> 📋 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
+## 🛠️ Tool Support
 
-# Compile TypeScript
-npm run build
+| CN | Global |
+| :--- | :--- |
+| WorkBuddy / Qcoder / Trae | Cursor / Claude Code / Windsurf / Gemini CLI / OpenCode |
 
-# Development mode (watch for file changes and auto-compile)
-npm run watch
+SpecCore CLI natively integrates WorkBuddy. Other tools supported via the SpecCore framework.
 
-# Local testing
-node bin/speccore --version
-
-# 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 +217,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>