speccore 5.22.3 → 5.22.5

package/README.en.md

@@ -1,99 +1,69 @@
 # SpecCore — Code by Spec, Not by Vibe
 
-SpecCore is a specification-driven development toolkit for AI-native teams. It orchestrates the full cycle: requirement analysis → task splitting → plan scheduling → code generation → archival handoff — all traceable and automated.
+**SpecCore is not a code generator — it's a human-AI collaboration operating system.** It turns requirements, splitting, planning, execution, and delivery into a closed loop — every step previewable and adjustable, ensuring human and AI reach consensus before a single line of code is written.
 
----
+> Juggling 5 microservices and 3 frontend platforms? SpecCore turns requirements → splits → plans → code → delivery into a traceable, automated pipeline.
 
-## Two Modes
-
-| | Simple (default) | Full |
-| :--- | :--- | :--- |
-| Commands | 17 core | 51 all |
-| For | Daily development | Fine-grained control |
-| Enable | `speccore init` | `speccore init --full` |
-
-**Simple mode commands:** `ask init iteration task doc2spec analyze split plan execute pr done change validate rename dev status-panel ops`
-
----
-
----
+```
+  init → doc2spec → analyze → split → plan → execute → pr → done
+  🚀Setup   📝Import   🧠Analyze  📦Split  📋Plan  💻Build  🔀PR  ✅Archive
+```
 
-## Quick Start
+## 🚀 5 Minutes to First Task
 
 ```bash
 npm install -g speccore
-speccore init                          # Initialize
-speccore iteration create --name=Q1    # Create iteration
-speccore doc2spec -f PRD.md -p backend -i Q1  # Import requirements
-speccore analyze -I Q1                 # Analyze (req+code, 3 scopes)
-speccore iteration split -i Q1         # Split into tasks
-speccore plan --iteration=Q1           # Generate plan
-speccore execute --task=Task-001       # AI development
-speccore pr --task=Task-001            # Create PR
-speccore done --task=Task-001          # Complete
+speccore init
+speccore doc2spec -f requirements.docx --iter=Q1   # Import PRD
+speccore analyze -I Q1                          # AI analysis + code health
+speccore iteration split -I Q1                  # Split into tasks
+speccore plan -I Q1                             # Generate plan
+speccore execute -t Task-001                    # AI-powered development
+speccore done --task=Task-001                       # Validate → archive
 ```
 
+## 🎯 What do you want to do?
 
-## Two Ways to Use
-
-Same command, different syntax depending on context:
-
-| Context | Syntax | Example |
-|:---|:---|:---|
-| 🖥 Terminal CLI | `speccore <command>` | `speccore init` `speccore execute -t Task-001 --force` |
-| 💬 AI Chat | Natural language | "Create a login feature" |
-| 💬 AI Chat | `/spec-<command>` | `/spec-init` `/spec-execute Task-001` |
-
-> Full reference (all 17 commands classified) → [Commands Reference — Two Ways to Use](docs/commands.en.md#-two-ways-to-use)
-
-## Interactive Mode
-
-Key steps support `--interactive` for human-AI collaboration:
-`analyze --ask` `split --interactive` `plan --interactive` `change --interactive`
-
-## Smart Entry
-
-```bash
-speccore                   # Adaptive panel
-speccore "analyze specs"   # Natural language (no subcommand needed)
-speccore dev               # Auto-detect phase + cascade execute
-```
+| I want to... | Command |
+|:---|:---|
+| **Start a new project** | `speccore init --interactive` |
+| **Import a PRD document** | `speccore doc2spec -f PRD.docx -I Q1` |
+| **Analyze requirements + code health** | `speccore analyze -I Q1` |
+| **Split requirements into tasks** | `speccore iteration split -I Q1 --interactive` |
+| **Fix a bug** | `speccore task new -n "Login timeout" --type=bugfix` |
+| **Batch fix bugs** | `speccore task new --batch-file=bugs.xlsx --type=bugfix` |
+| **Schedule overnight execution** | `speccore schedule create --at "02:00" --all -I Q1` |
+| **AI auto-development** | `speccore execute -t Task-001` |
+| **Create a Pull Request** | `speccore pr --task=Task-001 --interactive` |
+| **Archive a completed task** | `speccore done --task=Task-001 --interactive` |
+| **Check project status** | `speccore` or `speccore status-panel` |
+| **Natural language queries** | `speccore ask "analyze current requirements"` |
 
-## Multi-Platform
+> 📋 Full command reference → [Command Reference](docs/commands.en.md) | 中文文档 → [README.zh.md](README.md)
 
-All steps support parallel multi-project: backend services (`backend/room-service/`) and frontend platforms (`frontend/web/`, `frontend/h5/`).
+## 🤝 Interactive Mode
 
-## Bug Fix
+6 commands support `--interactive` — preview changes before confirming:
 
-```bash
-speccore task new --name="Login timeout" --desc="Token expiry" --type=bugfix              # Single
-speccore task new --batch-file=bugs.xlsx --type=bugfix                                    # Batch import
-speccore task new --batch-file=bugs.xlsx --type=bugfix --interactive                      # Confirm each
-```
+| `🧠 analyze --ask` | `🧠 split --interactive` | `🧠 plan --interactive` |
+|:---|:---|:---|
+| `🧠 pr --interactive` | `🧠 change --interactive` | `🧠 done --interactive` |
 
-## Scheduled Execution
+## ⏰ Scheduled Execution
 
 ```bash
-# Method 1: Mark tasks for queue, trigger manually
-speccore task new -n "Fix login timeout" --type=bugfix --schedule=night   # Mark as queue
-speccore execute --all --scheduled                                        # Run all queued tasks
-
-# Method 2: Precise time scheduling
-speccore schedule create --at "2026-08-10 21:00:00" -t Task-001          # Schedule single task
-speccore schedule create --at "2026-08-10 02:00:00" --all -i Q1          # Schedule all tasks
-speccore schedule list                                                     # View schedule queue
-speccore schedule cancel --id=sch-xxx                                      # Cancel
-speccore schedule daemon start                                             # Start daemon (auto-execute)
-speccore schedule daemon status                                            # Check daemon status
+speccore task new -n "Data migration" --schedule=night         # Queue for night
+speccore execute --all --scheduled                              # Run all queued
+speccore schedule create --at "2026-08-10 02:00" --all -I Q1   # Exact time
+speccore schedule daemon start                                   # Auto-execute on schedule
 ```
 
-## Documentation
+## 📚 Documentation
 
 | Doc | Content |
-| :--- | :--- |
-| 🚀 [Quick Start](docs/快速开始.md) | Full tutorial |
-| 🔧 [Full Command Reference](docs/命令参考.md) | 51 commands |
-| [Scenarios](docs/场景实战.md) | Typical use cases |
-| [Overview](docs/总览.md) | Architecture + concepts |
-| [SDD Methodology](docs/SDD方法论.md) | Why Spec-Driven Development |
-| [Examples](examples/meeting-system/README.md) | Meeting booking system demo |
+|:---|:---|
+| 🚀 [Quick Start](docs/quick-start.en.md) | Full tutorial |
+| 🔧 [Command Reference](docs/commands.en.md) | All 51 commands |
+| 🎬 [Scenarios](docs/scenarios.en.md) | Real-world examples |
+| 🗺 [Overview](docs/总览.md) | Architecture & philosophy |
+| 📝 [SDD Methodology](docs/sdd-methodology.en.md) | Spec-driven development |

package/README.md

@@ -1,161 +1,75 @@
 # SpecCore — Code by Spec, Not by Vibe
 
-SpecCore 是一套面向 AI 原生团队的规范驱动研发工具链。将需求分析、任务拆分、计划编排、代码生成、归档交接串联为可追溯的自动化流程。
+**SpecCore 是一套面向 AI 原生团队的规范驱动工具链。** 它用「Spec 先行」的方式把需求、拆分、计划、执行、交付串成一个闭环——人和 AI 在每个关键节点预览、调整、确认，生成的代码自然对齐需求。
 
----
+> 同时维护 5 个微服务和 3 个前端平台？SpecCore 把「需求 → 拆分 → 计划 → 执行 → 交付」串成一条可追溯的自动化流水线。
 
----
-
-## 两种模式
-
-| | 简洁模式（默认） | 全量模式 |
-| :--- | :--- | :--- |
-| 命令数 | 17 个核心命令 | 51 全部命令 |
-| 适用 | 日常开发够用 | 精细控制 |
-| 开启 | `speccore init` | `speccore init --full` |
-| 帮助 | `speccore --help` | 同上 |
-
-**简洁模式 17 个命令：**
 ```
-ask  init  iteration  task  doc2spec
-analyze  split  plan  execute  pr  done
-change  validate  rename  dev  status-panel  ops
+  init → doc2spec → analyze → split → plan → execute → pr → done
+  🚀初始化   📝导入需求   🧠分析   📦拆分   📋计划   💻执行   🔀提交   ✅收尾
 ```
 
----
-
-## 安装
+## 🚀 5 分钟体验
 
 ```bash
-npm install -g speccore
+npm install -g speccore                 # 安装
+speccore init                           # 初始化项目
+speccore doc2spec -f PRD.docx --iter=Q1     # 导入需求文档
+speccore analyze -I Q1                  # AI 分析需求 + 代码检查
+speccore iteration split -I Q1          # 拆分为独立 Task
+speccore plan -I Q1                     # 生成执行计划
+speccore execute -t Task-001            # AI 自动开发
+speccore done --task=Task-001               # 收尾归档
 ```
 
-## 核心流程
-
-```bash
-speccore init                          # ① 初始化
-speccore iteration create --name=Q1    # ② 新建期次
-speccore doc2spec -f PRD.md -p backend -i Q1  # ③ 导入需求文档
-speccore analyze -I Q1                 # ④ 需求分析
-speccore analyze --scope global --depth deep  # ④ 或：全局代码健康
-speccore iteration split -i Q1         # ⑤ 拆分 Task
-speccore plan -i Q1                    # ⑥ 执行计划
-speccore execute -t Task-001           # ⑦ AI 开发
-speccore pr -t Task-001                # ⑧ 提交 PR
-speccore done -t Task-001              # ⑨ 完成任务
-```
-
-
-## 两种用法
+## 🎯 我想...
 
-同一个命令有两种使用场景，写法不同：
-
-| 场景 | 写法 | 示例 |
+| 我想... | 用这个 |
+|:---|:---|
+| **新建项目** | `speccore init --interactive` |
+| **导入 PRD 文档** | `speccore doc2spec -f PRD.docx -I Q1` |
+| **分析需求 + 代码健康** | `speccore analyze -I Q1` / `--scope global` |
+| **拆分需求为 Task** | `speccore iteration split -I Q1 --interactive` |
+| **生成执行计划** | `speccore plan -I Q1 --interactive` |
+| **查看计划历史** | `speccore plan --list` / `plan --show plan-xxx` |
+| **修复一个 Bug** | `speccore task new -n "登录超时" --type=bugfix` |
+| **批量修复 Bug** | `speccore task new --batch-file=bugs.xlsx --type=bugfix` |
+| **定时自动执行** | `speccore schedule create --at "02:00" --all -I Q1` |
+| **AI 自动开发** | `speccore execute -t Task-001` / `--plan=plan-xxx` |
+| **创建 Pull Request** | `speccore pr --task=Task-001 --interactive` |
+| **收尾归档** | `speccore done --task=Task-001` / `done --all -I Q1 --interactive` |
+| **查看到哪了** | `speccore status-panel` 或直接 `speccore` |
+| **自然语言说需求** | `speccore ask "帮我分析当前需求"` |
+
+> 📋 全部 51 个命令 → [命令参考手册](docs/命令参考.md)
+
+## 🤝 协作模式
+
+6 个命令支持 `--interactive` 人机协作，预览变更后才确认执行：
+
+| `🧠 analyze --ask` | `🧠 split --interactive` | `🧠 plan --interactive` |
 |:---|:---|:---|
-| 🖥 终端 CLI | `speccore <命令>` | `speccore init` `speccore execute -t Task-001 --force` |
-| 💬 AI 对话 | 直接说人话 | "帮我创建登录功能" |
-| 💬 AI 对话 | `/spec-<命令>` | `/spec-init` `/spec-execute Task-001` |
-
-> 完整对照表（所有 17 个命令的分类说明）→ [命令参考 — 两种使用方式](docs/命令参考.md#-两种使用方式)
-
-## 交互模式
-
-关键步骤支持 `--interactive` 人机协作：
-
-| 命令 | 交互步骤 |
-| :--- | :--- |
-| `analyze --ask` | AI 提问 → 用户回答 → 调整分析 |
-| `split --interactive` | 预览 Task 列表 → 逐一确认/取消 |
-| `plan --interactive` | 预览调��方案 → 确认/取消 |
-| `change --interactive` | 预览影响范围 → 确认 → 应用 |
-| `pr --interactive` | 选文件 → commit → push → 创建 PR |
-| `done --interactive` | 预览步骤 → 跳过选项 → 确认执行 |
-| `init --interactive` | 选模式 → 确认 → 初始化 |
-
-## 智能入口
-
-```bash
-speccore                          # 自适应面板：检测当前阶段 → 提示下一步
-speccore ask "分析当前需求"        # 自然语言意图识别
-speccore "帮我拆分任务"            # 直接输入，无需子命令
-speccore dev                      # 一键级联：自动检测并执行下一步
-```
-
-## 多端支持
-
-所有步骤原生支持多工程并行：后端多个服务（`backend/room-service/`、`backend/booking-service/`）、前端多个平台（`frontend/web/`、`frontend/h5/`）。
+| `🧠 pr --interactive` | `🧠 change --interactive` | `🧠 done --interactive` |
 
-## Bug 修复
+## ⏰ 调度执行
 
-`task new --type=bugfix` 创建 Bug 任务，支持单条、批量、调度：
+指定时间自动执行。`--all` 会按依赖排序、分批执行当期次所有任务：
 
 ```bash
-speccore task new -n "登录超时" -d "Token 过期后未刷新" --type=bugfix        # 单条
-speccore task new --batch-file=bugs.xlsx --type=bugfix                        # 批量导入
-speccore task new --batch-file=bugs.xlsx --type=bugfix --interactive          # 逐条确认
-```
-
-## 调度执行
-
-两种粒度的调度，支持指定任意时间：
-
-```bash
-# ── 方式 1: 创建任务时标记 ──
-speccore task new -n "修复登录超时" --type=bugfix --schedule=night   # 标记为 queue
-speccore execute --all --scheduled                                      # 手动触发所有 queue 任务
-
-# ── 方式 2: 精确时间调度（支持人员、分批、类型等所有 execute 筛选参数）──
-speccore schedule create --at "2026-08-10 21:00:00" -t Task-001              # 单个任务定时
-speccore schedule create --at "2026-08-10 02:00:00" --all -i Q1 \
-  -a 张三 --batch-size=3 --type=bugfix                                         # 指定人员+分批+类型
-speccore schedule daemon start                                                 # 启动守护进程
-speccore schedule list                                                         # 查看队列
-speccore schedule cancel --id=sch-xxx                                          # 取消
-```
-
-`execute` 自动能力：
-
-| 能力 | 说明 |
-|:---|:---|
-| 依赖排序 | 自动分析 Task 间依赖关系，按拓扑顺序执行 |
-| 分批执行 | `--batch-size=3`（默认），每批做完再继续 |
-| 断点续传 | `--resume` 从上次中断位置继续 |
-| 多条件筛选 | `--priority high` `--type feature` `--platform web` 只跑指定条件 |
-
-> `execute --all` 跑 todo 任务，`execute --all --scheduled` 跑 queue 任务，互不干扰。
-
-
-## 目录结构
-
-```
-项目/
-├── .speccore/
-│   ├── CONSTITUTION.md       # 技术宪法
-│   ├── GLOBAL/               # 全局层（架构文档、代码健康报告）
-│   └── RULES/                # 编码规则
-│
-└── 期次-Q1/
-    ├── 00-需求文档/           # 需求文档 + ANALYSIS.md
-    ├── Task-001/
-    │   ├── TASK.md
-    │   ├── backend/{服务名}/  # 按服务分目录
-    │   │   ├── TASK.md
-    │   │   └── API_CONTRACT.yaml
-    │   └── frontend/{平台}/   # 按平台分目录
-    │       └── TASK.md
-    └── Task-002/
+speccore schedule create --at "2026-08-10 02:00:00" --all -I Q1       # 全部任务，自动排序
+speccore schedule create --at "2026-08-10 21:00:00" -t Task-001         # 单个任务
+speccore schedule create --at "02:00" --all -I Q1 -a 张三 --type=bugfix  # 筛选后执行
+speccore schedule daemon start                                           # 启动守护进程
 ```
 
----
+> 不需要手动 `plan`——`execute` 自动分析 Task 依赖，按拓扑顺序分批执行。`--batch-size=3` 控制每批数量。
 
-## 文档
+## 📚 了解更多
 
 | 文档 | 内容 |
-| :--- | :--- |
-| 🚀 [快速开始](docs/快速开始.md) | 完整安装 → 使用教程 |
-| 🔧 [全量命令参考](docs/命令参考.md) | 51 命令完整说明（高级用户） |
-| [场景实战](docs/场景实战.md) | 日常开发典型场景 |
-| [总览](docs/总览.md) | 架构概览 + 理念 |
-| [SDD 方法论](docs/SDD方法论.md) | 规范驱动开发介绍 |
-| [Spec 加载机制](docs/Spec三层加载机制.md) | 三层 Spec 协同 |
-| [示例项目](examples/meeting-system/README.md) | 会议预订系统完整演示 |
+|:---|:---|
+| 🚀 [快速开始](docs/快速开始.md) | 完整安装与使用教程 |
+| 🔧 [命令参考](docs/命令参考.md) | 51 个命令完整说明 |
+| 🎬 [场景实战](docs/场景实战.md) | 33 个真实开发场景 |
+| 🗺 [总览](docs/总览.md) | 架构概览与设计理念 |
+| 📝 [SDD 方法论](docs/SDD方法论.md) | 规范驱动开发介绍 |