@culeo/specx 0.1.0

package/README.md

@@ -0,0 +1,154 @@
+# specx
+
+> 企业级 AI 研发流程 — 需求 → 澄清 → 规格 → 设计 → 任务 → 执行 → 归档
+
+specx 是一套企业级研发流程 skill 系列，核心理念是**先签合同再施工**：以规格说明书为蓝图，原子化执行，可追溯可回滚。
+
+---
+
+## 🎯 核心理念
+
+| | 传统开发 | specx |
+|---|---|---|
+| **核心资产** | 代码 | 规格说明书（Spec） |
+| **开发模式** | 边做边改 | 先签合同再施工 |
+| **AI 协作** | AI 自由发挥 | AI 照"蓝图"执行 |
+| **交付风险** | 不可控、难审查 | 原子化、可回滚 |
+
+---
+
+## 📦 Skill 系列
+
+| Skill | 功能 | 状态 |
+|-------|------|------|
+| `specx-demystify` | 需求分析 & 领域拆解 | ✅ 完成 |
+| `specx-clarify` | 需求澄清 & 规格输出 | ✅ 完成 |
+| `specx-design` | 实现规划 & 详细设计 | ✅ 完成 |
+| `specx-create-design-template` | 生成项目专属设计模板 | ✅ 完成 |
+| `specx-writing-plans` | 设计文档转任务清单 | ✅ 完成 |
+| `specx-executing-plans` | 执行任务清单 | ✅ 完成 |
+| `specx-archive` | 归档沉淀到 wiki | ✅ 完成 |
+| `specx-create-rule` | 创建/维护框架规范 | ✅ 完成 |
+| `specx-docs-align` | 文档对齐检查 | ✅ 完成 |
+
+---
+
+## 🔄 完整流程
+
+```
+需求输入（PRD / 需求文档）
+           │
+           ▼
+┌─────────────────────┐
+│ specx-demystify      │  ← Step 1：拆解需求
+│  • MECE 领域划分      │     产出：原子化子需求
+│  • MoSCoW 优先级      │
+│  • 依赖关系分析        │
+└──────────┬──────────┘
+           ▼
+┌─────────────────────┐
+│ specx-clarify       │  ← Step 2：需求澄清
+│  • 用户场景           │     产出：01-clarify.md
+│  • 功能要点 & 边界     │            02-spec.md
+│  • Q&A 迭代          │
+└──────────┬──────────┘
+           ▼
+┌─────────────────────┐
+│ specx-design        │  ← Step 3：实现规划
+│  • 整体架构           │     产出：03-design.md
+│  • 各平台详细设计      │     （按项目模板）
+│  • 可复用组件          │
+└──────────┬──────────┘
+           ▼
+┌─────────────────────┐
+│ specx-writing-plans │  ← Step 4：任务拆解
+│  • 任务清单           │     产出：04-tasks.md
+│  • 并行组 & 依赖      │
+│  • MoSCoW 优先级      │
+└──────────┬──────────┘
+           ▼
+┌─────────────────────┐
+│ specx-executing-plans│  ← Step 5：执行
+│  • 原子任务执行        │     产出：代码
+│  • 小 PR 产出         │
+└──────────┬──────────┘
+           ▼
+┌─────────────────────┐
+│ specx-archive       │  ← Step 6：归档
+│  • 提炼到 wiki       │     产出：docs/specx/wiki/
+│  • 知识沉淀           │
+└─────────────────────┘
+```
+
+---
+
+## 📂 目录结构
+
+```
+docs/specx/
+├── spaces/                    # 需求空间（每个需求独立目录）
+│   └── {yyyyMMdd}-{需求摘要}/
+│       ├── Raws/               # 原始需求来源（多源分类）
+│       │   ├── P001-{需求名称}.md       # 产品需求文档
+│       │   ├── U001-{用户反馈}.md       # 用户输入/语料
+│       │   └── ...
+│       ├── T-01-{子需求名}/
+│       │   ├── 00-子需求.md            # 子需求原始描述（由 demystify 产出）
+│       │   ├── 01-clarify.md           # 澄清记录
+│       │   ├── 02-spec.md              # 规格说明书
+│       │   ├── 03-design.md            # 设计方案
+│       │   └── 04-tasks.md             # 任务清单
+│       └── T-02-{子需求名}/
+│           └── ...
+├── wiki/                      # 项目知识库（归档沉淀）
+├── rule/                      # 框架规范
+└── templates/                 # 项目专属模板
+```
+
+---
+
+## 🧩 关键约定
+
+- **文件名规范**：`00-子需求.md` / `01-clarify.md` / `02-spec.md` / `03-design.md` / `04-tasks.md`
+- **wiki 知识沉淀**：`docs/specx/wiki/`，由 `specx-archive` 维护
+- **框架规范**：`docs/specx/rule/`，clarify 时跳过已有规范，不重复提问
+- **项目模板**：`docs/specx/templates/`，首次 design 时生成
+
+---
+
+## 🚀 快速开始
+
+```bash
+# 安装依赖
+npm install
+
+# 交互式安装（选择目标 + 选择用户/项目级）
+specx install
+
+# 指定目标安装
+specx install --claude            # 装到 Claude Code（用户级）
+specx install --codex             # 装到 Codex（用户级）
+specx install --claude --codex    # 装到两边
+
+# 项目级安装（.claude/skills/）
+specx install --claude --project
+
+# 非交互式：装到所有已检测的工具
+specx install --all
+
+# 查看已安装的 specx skills
+specx list
+
+# 查看可用 skills
+specx available
+
+# 卸载
+specx uninstall --claude
+specx uninstall --codex --project
+```
+
+---
+
+## 📝 License
+
+Internal use only.

package/package.json

@@ -0,0 +1,30 @@
+{
+  "name": "@culeo/specx",
+  "version": "0.1.0",
+  "description": "Install specx skills to AI coding agents (Claude Code, Codex, etc.)",
+  "type": "module",
+  "bin": {
+    "specx": "./specx.js"
+  },
+  "dependencies": {
+    "commander": "^12.0.0"
+  },
+  "engines": {
+    "node": ">=18"
+  },
+  "license": "MIT",
+  "publishConfig": {
+    "access": "public"
+  },
+  "repository": {
+    "type": "git",
+    "url": "git@github.com:leo/specx.git"
+  },
+  "keywords": [
+    "specx",
+    "claude-code",
+    "codex",
+    "ai-coding",
+    "skills"
+  ]
+}

package/skills/specx-archive/SKILL.md

@@ -0,0 +1,235 @@
+---
+name: specx-archive
+description: specx 流程最后一步 — 将已完成的需求文档（clarify.md / spec.md / design.md）归纳总结，写入项目 docs/specx/wiki/ 目录，形成可查询的知识库。
+category: software-development
+tags: [specx, archive, wiki, knowledge]
+---
+
+# specx-archive：归档沉淀
+
+## 触发条件
+
+当一个子需求完成（clarify → spec → design → code 全部走完）后，用户说"归档"、"沉淀到 wiki"、"完成这个需求"时使用。
+
+**前置判断：** 子需求目录 `T-xx/` 下已有 `clarify.md`、`spec.md`、`design.md`（及可选 `code` 相关文档）。
+
+**不是触发的情况：**
+- 需求还在中途（未完成 code）
+- 用户只是问问题，不是正式完成需求
+
+---
+
+## 输入
+
+- `T-xx/00-子需求.md` — 原始需求
+- `T-xx/01-clarify.md` — 澄清后的需求
+- `T-xx/02-spec.md` — 规格说明书
+- `T-xx/03-design.md` — 设计方案
+- `T-xx/04-tasks.md` — 任务清单（已完成的）
+
+---
+
+## 输出
+
+写入 `docs/specx/wiki/` 下的页面文件，形成项目知识库，供后续查询和复用。
+
+---
+
+## wiki 目录结构
+
+每个条目独立文件，不放在单个大文件里。避免膨胀，难以维护。
+
+```
+docs/specx/wiki/
+├── README.md                    # 知识库入口 & 总索引
+├── entities/                    # 领域概念
+│   └── {slug}.md
+├── features/                    # 功能模块
+│   └── {slug}.md
+├── decisions/                   # 技术决策
+│   └── {slug}.md
+└── components/                  # 组件说明
+    └── {slug}.md
+```
+
+### 命名规则
+
+- 文件名：`{T-xx}-{简短英文名}.md`，小写，连字符分隔
+- 示例：`T01-stock-card.md`、`T03-redis-cache.md`
+
+> 首次归档时由本 skill 创建 `docs/specx/wiki/` 目录和 `README.md`。
+
+---
+
+## Step 1️⃣ 读取子需求文档
+
+按顺序读：
+1. `00-子需求.md` — 了解原始需求背景
+2. `01-clarify.md` — 核心澄清点（消歧后的需求）
+3. `02-spec.md` — 验收标准
+4. `03-design.md` — 实现要点
+5. `04-tasks.md` — 任务完成情况
+
+---
+
+## Step 2️⃣ 判断写入哪个 wiki 分类
+
+根据内容判断归档到哪个子目录：
+
+| 内容类型 | 写入子目录 |
+|---------|---------|
+| 新概念/名词/领域模型 | `entities/` |
+| 功能模块描述（做什么）| `features/` |
+| 技术选型、架构决策、为什么这样做 | `decisions/` |
+| UI 组件、复用组件说明 | `components/` |
+
+> 如果不确定，写入 `features/`。
+
+---
+
+## Step 3️⃣ 提炼写入内容
+
+### 对每个分类的提炼要求
+
+**entities/ — 实体沉淀：**
+- 核心领域名词的定义
+- 概念之间的关系（与哪些其他实体相关）
+- 业务含义（区别于纯技术命名）
+
+**features/ — 功能沉淀：**
+- 功能名称和一句话描述
+- 触发场景（用户怎么用到这个功能）
+- 输入/前置条件
+- 输出/后置结果
+- 与其他功能的依赖关系
+
+**decisions/ — 决策沉淀：**
+- 决策点（"为什么选择 X 而不是 Y"）
+- 约束条件（技术限制、业务限制）
+- 最终选择及理由
+- 替代方案及否定原因
+
+**components/ — 组件沉淀：**
+- 组件名称和职责
+- Props / 参数说明
+- 使用场景
+- 与其他组件的组合关系
+
+---
+
+## Step 4️⃣ 写入 wiki 页面
+
+按相关性分组写到同一文件。文件内容超过 200 行时，拆分为独立文件。
+
+### 文件命名
+
+- 路径：`docs/specx/wiki/{分类}/{英文名}.md`
+- 示例：`docs/specx/wiki/features/stock-card.md`
+
+### 单文件内容格式
+
+**独立条目：** 每个文件一个 `##` 标题。
+**合并组：** 多个 `##` 条目共享一个文件级别的 `**分类**`、`**最后更新时间**`。
+
+```markdown
+# {组名/条目名}
+
+**分类：** {entities/features/decisions/components}
+**最后更新时间：** {YYYY-MM-DD}
+**关联需求：**
+- [T-xx](../{需求目录}/T-xx/00-子需求.md)
+
+---
+
+## {条目名}
+
+{内容}
+
+---
+
+## {条目名}
+
+{内容}
+```
+
+### 更新 README.md 索引
+
+首次创建 wiki 时写入：
+
+```markdown
+# Wiki
+
+> 项目知识库 — 由 specx-archive 维护
+
+## 分类
+
+- `entities/` — 领域概念、名词解释
+- `features/` — 功能模块说明
+- `decisions/` — 技术决策记录
+- `components/` — 组件说明
+
+## 最近更新
+
+| 日期 | 分类 | 文件 | 内容摘要 |
+|------|------|------|---------|
+| {YYYY-MM-DD} | {分类} | {文件名} | {一句话描述} |
+```
+
+后续归档时，在"最近更新"表格**顶部**插入新行。
+
+---
+
+## Step 5️⃣ 更新文档状态为 archived
+
+归档完成后，更新子需求目录下所有产出文档的文件头状态为 `archived`：
+
+```markdown
+// 对 01-clarify.md / 02-spec.md / 03-design.md / 04-tasks.md 逐一更新
+
+---
+status: archived
+updated: {YYYY-MM-DD}
+history:
+  - "v1: 初始创建"
+  - "v2: ..."
+  - "v3: docs-align 修正: ..."
+  - "v4: 已归档到 wiki"
+---
+```
+
+## Step 6️⃣ 更新子需求目录状态
+
+在 `T-xx/` 下的 `README.md`（如果没有就创建）标注归档状态：
+
+```markdown
+# T-{xx}-{子需求名称}
+
+**状态：** ✅ 已归档
+**最后更新时间：** {YYYY-MM-DD}
+**Wiki 沉淀位置：**
+- [T-xx-{slug}](../wiki/{分类}/T-xx-{slug}.md)
+```
+
+---
+
+## 归档质量清单
+
+```
+[ ] 已读取全部子需求文档（00-子需求/clarify/spec/design/tasks）
+[ ] 判断了正确的 wiki 分类（entities/features/decisions/components）
+[ ] 每个提炼内容写成独立文件
+[ ] 文件名符合命名规则 {T-xx}-{slug}.md
+[ ] 更新了 README.md 索引（顶部插入新行）
+[ ] 标注了子需求目录为已归档
+[ ] 未污染原始文档（clarify/spec/design.md 未被修改）
+```
+
+---
+
+## 重要提示
+
+- **不是复制粘贴** — 提炼精华，不是把整个文档搬进去
+- **不修改原始文档** — 归档是新建文件，原始 clarify/spec/design.md 保持不变
+- **先判断分类再写** — 不确定时优先选 features/
+- **按相关性分组** — 相关条目放同一文件，超过 200 行则拆分
+- **索引要维护** — 每次归档都要更新 README.md 的最近更新表格（顶部插入）