speccore 4.6.0 → 4.6.1

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
  1. package/README.en.md +19 -14
  2. package/README.md +45 -14
  3. package/package.json +1 -1
package/README.en.md CHANGED
@@ -1,4 +1,4 @@
1
- # SpecCore CLI
1
+ # SpecCore
2
2
 
3
3
  > **Code by Spec, Not by Vibe.**
4
4
 
@@ -6,7 +6,7 @@
6
6
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
7
7
  [![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)
8
8
 
9
- 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.
9
+ SpecCore is a specification-driven development framework for AI-native teams. 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.
10
10
 
11
11
  > 💡 **v4.0.0** | 39 Commands | 31 Intent Types | Multi-Platform
12
12
 
@@ -165,7 +165,7 @@ Iteration-XXX/ ← Iteration Layer: what this iteration does
165
165
  | :--- | :--- |
166
166
  | WorkBuddy / Qcoder / Trae | Cursor / Claude Code / Windsurf / Gemini CLI / OpenCode |
167
167
 
168
- SpecCore CLI natively integrates WorkBuddy. Other tools supported via the SpecCore framework.
168
+ SpecCore natively integrates WorkBuddy.
169
169
 
170
170
  > 📚 See [Tool Adaptation](docs/tool-adaptation.en.md)
171
171
 
@@ -181,7 +181,9 @@ SpecCore CLI natively integrates WorkBuddy. Other tools supported via the SpecCo
181
181
  | [命令参考手册](docs/命令参考.md) | 🇨🇳 | 39 个命令完整参数 + 31 种意图映射 + 别名速查 |
182
182
  | [Tool Adaptation](docs/tool-adaptation.en.md) | 🇬🇧 | WorkBuddy integration + workflow + security |
183
183
  | [工具适配说明](docs/工具适配说明.md) | 🇨🇳 | WorkBuddy 集成原理 + 工作流程 + 安全检查 |
184
- | [CHANGELOG](CHANGELOG.md) | 🇨🇳 | Version history (v1.0.0 → v4.0.0) |
184
+ | [Usage Guide](docs/使用指南.md) | 🇨🇳 | File safety: what to edit manually vs via command |
185
+ | [Migration Guide](docs/migration-guide.md) | 🇨🇳 | Shell v3.x → CLI v4.x migration |
186
+ | [CHANGELOG](CHANGELOG.md) | 🇨🇳 | Version history (v1.0.0 → v4.6.0) |
185
187
  | [README.md](README.md) | 🇨🇳 | 中文项目概述 |
186
188
 
187
189
  ---
@@ -198,6 +200,18 @@ SpecCore CLI natively integrates WorkBuddy. Other tools supported via the SpecCo
198
200
  | **Batch rename?** | `speccore rename --batch --pattern="Task-" --replacement="Feature-"` |
199
201
  | **Rebuild requirement index?** | `speccore index-update` (--dry-run to preview) |
200
202
 
203
+ | **Which files are safe to edit manually?** | See [Usage Guide](docs/使用指南.md). TL;DR: `REQ.md`/`TECH.md` safe; `API_CONTRACT.yaml`/`.json` require CLI commands. |
204
+
205
+ ---
206
+
207
+ ## File Safety Quick Reference
208
+
209
+ | Zone | Files | Rule |
210
+ | :--- | :--- | :--- |
211
+ | ✅ Safe | `REQ.md`, `TECH.md`, `GLOSSARY.md`, `*.md` comments | Edit directly, then `speccore sync --reverse` |
212
+ | ❌ Danger | `PROJECT_GRAPH.md` tables, `.task-type`, `API_CONTRACT.yaml`, `.json` data | Use `speccore` commands instead |
213
+ | ⚠️ Caution | `GLOBAL/REQUIREMENT.md`, `CHANGELOG.md` | Edit then immediately run `speccore sync-global` |
214
+
201
215
  ---
202
216
 
203
217
  ## Development
@@ -213,18 +227,9 @@ bash verify.sh # Run tests
213
227
 
214
228
  ---
215
229
 
216
- ## Related Projects
217
-
218
- | Project | Description | Link |
219
- | :--- | :--- | :--- |
220
- | **SpecCore Framework** | Spec-driven methodology + Slash Commands + templates | [GitHub](https://github.com/windfallsheng/SpecCore) |
221
- | **SpecCore CLI** | TypeScript CLI tool (deterministic execution engine) | [GitHub](https://github.com/windfallsheng/SpecCore-ts) |
222
-
223
- ---
224
-
225
230
  ## Version
226
231
 
227
- v4.0.0 | 🔧 CLI Commands: 39 | 🧠 Intents: 31
232
+ v4.6.0 | 🔧 CLI Commands: 40 | 🧠 Intents: 31
228
233
 
229
234
  Changelog: [CHANGELOG.md](CHANGELOG.md)
230
235
 
package/README.md CHANGED
@@ -1,4 +1,4 @@
1
- # SpecCore CLI
1
+ # SpecCore
2
2
 
3
3
  > **Code by Spec, Not by Vibe.**
4
4
 
@@ -6,7 +6,7 @@
6
6
  [![License: MIT](https://img.shields.io/badge/License-MIT-yellow.svg)](https://opensource.org/licenses/MIT)
7
7
  [![Node.js](https://img.shields.io/badge/Node.js-%3E%3D18.0.0-brightgreen.svg)](https://nodejs.org/)
8
8
 
9
- SpecCore CLI 是 [SpecCore 规范驱动开发框架](https://github.com/windfallsheng/SpecCore) 的官方 TypeScript 命令行工具。它将确定性操作（文件创建、目录管理、格式校验、状态统计）从 AI 中剥离，由代码直接执行，提升效率并降低 Token 消耗。
9
+ SpecCore 是一套可落地的、面向 AI 原生团队的规范驱动研发工程框架。它将确定性操作（文件创建、目录管理、格式校验、状态统计）从 AI 中剥离，由代码直接执行，提升效率并降低 Token 消耗。
10
10
 
11
11
  ---
12
12
 
@@ -165,7 +165,7 @@ SpecCore 采用**确定性逻辑与智能逻辑解耦**的架构：
165
165
  | :--- | :--- |
166
166
  | WorkBuddy / Qcoder / Trae | Cursor / Claude Code / Windsurf / Gemini CLI / OpenCode |
167
167
 
168
- SpecCore CLI 原生集成 WorkBuddy（`speccore init` 自动创建 `.workbuddy/` skill 和 memory）。其他工具通过 SpecCore 源项目适配。
168
+ SpecCore 原生集成 WorkBuddy（`speccore init` 自动创建 `.workbuddy/` skill 和 memory）。
169
169
 
170
170
  > 📚 完整适配说明见 [工具适配说明](docs/工具适配说明.md)
171
171
 
@@ -181,7 +181,9 @@ SpecCore CLI 原生集成 WorkBuddy（`speccore init` 自动创建 `.workbuddy/`
181
181
  | [Command Reference](docs/commands.en.md) | 🇬🇧 | 39 commands full params + 31 intents + aliases |
182
182
  | [工具适配说明](docs/工具适配说明.md) | 🇨🇳 | WorkBuddy 集成原理 + 工作流程 + 安全检查 |
183
183
  | [Tool Adaptation](docs/tool-adaptation.en.md) | 🇬🇧 | WorkBuddy integration + workflow + security |
184
- | [CHANGELOG](CHANGELOG.md) | 🇨🇳 | 版本历史与更新日志（v1.0.0 → v4.0.0） |
184
+ | [使用指南](docs/使用指南.md) | 🇨🇳 | 文件操作安全指南：哪些可手动改、哪些必须用命令 |
185
+ | [迁移指南](docs/migration-guide.md) | 🇨🇳 | Shell v3.x → CLI v4.x 迁移步骤 |
186
+ | [CHANGELOG](CHANGELOG.md) | 🇨🇳 | 版本历史与更新日志（v1.0.0 → v4.6.0） |
185
187
  | [README.en.md](README.en.md) | 🇬🇧 | English project overview |
186
188
 
187
189
  ---
@@ -199,6 +201,44 @@ SpecCore CLI 原生集成 WorkBuddy（`speccore init` 自动创建 `.workbuddy/`
199
201
  | **手动改了文档，需要同步？** | `speccore sync --task=Task-001` 或 `speccore sync-global` |
200
202
  | **需求编号重复？** | `speccore validate --fix` 自动检测修复 |
201
203
  | **如何重建需求索引？** | `speccore index-update`（--dry-run 预览） |
204
+ | **哪些文件可以手动改？** | 见下方 [文件操作安全指南](#文件操作安全指南) |
205
+
206
+ ---
207
+
208
+ ## 文件操作安全指南
209
+
210
+ SpecCore 不禁止手动编辑文件，但不同文件的安全级别不同。
211
+
212
+ ### ✅ 安全区 — 可以直接手动改
213
+
214
+ 这些文件是"描述性文字"，CLI 不会覆盖它们：
215
+
216
+ | 文件 | 内容 | 改完后 |
217
+ | :--- | :--- | :--- |
218
+ | `REQ.md` | 需求描述、背景、业务规则 | `speccore sync --reverse --task=xxx` 回写数据库 |
219
+ | `TECH.md` | 技术方案描述、设计思路 | 直接改即可，无需同步 |
220
+ | `GLOSSARY.md` | 术语定义 | `speccore sync --reverse` 更新索引 |
221
+ | `*.md` 注释行 | 备注、TODO、注意事项 | 不影响任何流程 |
222
+
223
+ ### ❌ 高风险区 — 必须用命令修改
224
+
225
+ 这些文件是"元数据/状态/关系"，手动改会被 CLI 覆盖或导致解析失败：
226
+
227
+ | 文件 | 错改后果 | 正确方式 |
228
+ | :--- | :--- | :--- |
229
+ | `PROJECT_GRAPH.md` 表格 | CLI 执行时直接覆盖 | `speccore plan --assign=张三` |
230
+ | `.task-type` | 类型错误影响整个生命周期 | `speccore new-task --type=feature` |
231
+ | `API_CONTRACT.yaml` | 缩进错误导致校验失败 | 编辑后用 `speccore validate` 验证 |
232
+ | `.speccore/data/*.json` | Zod 枚举拼写错误导致卡死 | `speccore change Task-001 "描述"` |
233
+
234
+ ### ⚠️ 慎改区 — 手动改完必须立即同步
235
+
236
+ | 文件 | 正确流程 |
237
+ | :--- | :--- |
238
+ | `GLOBAL/REQUIREMENT.md` | 改完立即 `speccore sync-global` |
239
+ | `CHANGELOG.md` | 建议用 `speccore change` 自动追加 |
240
+
241
+ > 📚 完整指南见 [使用指南](docs/使用指南.md)
202
242
 
203
243
  ---
204
244
 
@@ -224,18 +264,9 @@ bash verify.sh
224
264
 
225
265
  ---
226
266
 
227
- ## 相关项目
228
-
229
- | 项目 | 说明 | 链接 |
230
- | :--- | :--- | :--- |
231
- | **SpecCore 框架** | 规范驱动开发方法论 + Slash Commands + 模板 | [GitHub](https://github.com/windfallsheng/SpecCore) |
232
- | **SpecCore CLI** | TypeScript CLI 工具（确定性操作执行引擎） | [GitHub](https://github.com/windfallsheng/SpecCore-ts) |
233
-
234
- ---
235
-
236
267
  ## 版本
237
268
 
238
- v4.0.0 | 🔧 CLI 命令 39 个 | 🧠 意图识别 31 种
269
+ v4.6.0 | 🔧 CLI 命令 40 个 | 🧠 意图识别 31 种
239
270
 
240
271
  版本历史见 [CHANGELOG.md](CHANGELOG.md)
241
272
 
package/package.json CHANGED
@@ -1,6 +1,6 @@
1
1
  {
2
2
  "name": "speccore",
3
- "version": "4.6.0",
3
+ "version": "4.6.1",
4
4
  "description": "SpecCore - Code by Spec, Not by Vibe.",
5
5
  "main": "dist/index.js",
6
6
  "types": "dist/index.d.ts",