specops 0.2.4 → 0.3.0

package/.opencode/templates/codebase/stack.md

@@ -0,0 +1,186 @@
+# 技术栈模板
+
+`.planning/codebase/STACK.md` 的模板 - 记录技术基础。
+
+**用途：** 记录本代码库运行的技术。聚焦于"运行代码时执行的是什么"。
+
+---
+
+## 文件模板
+
+```markdown
+# 技术栈
+
+**分析日期：** [YYYY-MM-DD]
+
+## 语言
+
+**主要：**
+- [语言] [版本] - [使用场景：例如 "所有应用代码"]
+
+**次要：**
+- [语言] [版本] - [使用场景：例如 "构建脚本、工具"]
+
+## 运行时
+
+**环境：**
+- [运行时] [版本] - [例如 "Node.js 20.x"]
+- [其他要求（如有）]
+
+**包管理器：**
+- [管理器] [版本] - [例如 "npm 10.x"]
+- 锁文件：[例如 "存在 package-lock.json"]
+
+## 框架
+
+**核心：**
+- [框架] [版本] - [用途：例如 "Web 服务器"、"UI 框架"]
+
+**测试：**
+- [框架] [版本] - [例如 "Jest 用于单元测试"]
+- [框架] [版本] - [例如 "Playwright 用于端到端测试"]
+
+**构建/开发：**
+- [工具] [版本] - [例如 "Vite 用于打包"]
+- [工具] [版本] - [例如 "TypeScript 编译器"]
+
+## 关键依赖
+
+[仅包含对理解技术栈至关重要的依赖 - 限制在 5-10 个最重要的]
+
+**核心：**
+- [包] [版本] - [重要原因：例如 "认证"、"数据库访问"]
+- [包] [版本] - [重要原因]
+
+**基础设施：**
+- [包] [版本] - [例如 "Express 用于 HTTP 路由"]
+- [包] [版本] - [例如 "PostgreSQL 客户端"]
+
+## 配置
+
+**环境：**
+- [配置方式：例如 ".env 文件"、"环境变量"]
+- [关键配置：例如 "需要 DATABASE_URL、API_KEY"]
+
+**构建：**
+- [构建配置文件：例如 "vite.config.ts、tsconfig.json"]
+
+## 平台要求
+
+**开发：**
+- [操作系统要求或"任何平台"]
+- [额外工具：例如 "Docker 用于本地数据库"]
+
+**生产：**
+- [部署目标：例如 "Vercel"、"AWS Lambda"、"Docker 容器"]
+- [版本要求]
+
+---
+
+*技术栈分析：[date]*
+*主要依赖变更后更新*
+```
+
+<good_examples>
+```markdown
+# 技术栈
+
+**分析日期：** 2025-01-20
+
+## 语言
+
+**主要：**
+- TypeScript 5.3 - 所有应用代码
+
+**次要：**
+- JavaScript - 构建脚本、配置文件
+
+## 运行时
+
+**环境：**
+- Node.js 20.x（LTS）
+- 无浏览器运行时（仅 CLI 工具）
+
+**包管理器：**
+- npm 10.x
+- 锁文件：存在 `package-lock.json`
+
+## 框架
+
+**核心：**
+- 无（原生 Node.js CLI）
+
+**测试：**
+- Vitest 1.0 - 单元测试
+- tsx - 无需构建步骤的 TypeScript 执行
+
+**构建/开发：**
+- TypeScript 5.3 - 编译为 JavaScript
+- esbuild - Vitest 使用的快速转换
+
+## 关键依赖
+
+**核心：**
+- commander 11.x - CLI 参数解析和命令结构
+- chalk 5.x - 终端输出样式
+- fs-extra 11.x - 扩展文件系统操作
+
+**基础设施：**
+- Node.js 内置模块 - fs、path、child_process 用于文件操作
+
+## 配置
+
+**环境：**
+- 不需要环境变量
+- 仅通过 CLI 标志配置
+
+**构建：**
+- `tsconfig.json` - TypeScript 编译器选项
+- `vitest.config.ts` - 测试运行器配置
+
+## 平台要求
+
+**开发：**
+- macOS/Linux/Windows（任何有 Node.js 的平台）
+- 无外部依赖
+
+**生产：**
+- 作为 npm 包分发
+- 通过 npm install -g 全局安装
+- 在用户的 Node.js 安装上运行
+
+---
+
+*技术栈分析：2025-01-20*
+*主要依赖变更后更新*
+```
+</good_examples>
+
+<guidelines>
+**STACK.md 中应包含的内容：**
+- 语言和版本
+- 运行时要求（Node、Bun、Deno、浏览器）
+- 包管理器和锁文件
+- 框架选择
+- 关键依赖（限制在 5-10 个最重要的）
+- 构建工具
+- 平台/部署要求
+
+**不应包含的内容：**
+- 文件结构（那是 STRUCTURE.md 的内容）
+- 架构模式（那是 ARCHITECTURE.md 的内容）
+- package.json 中的每个依赖（仅关键的）
+- 实现细节（参考代码）
+
+**填写此模板时：**
+- 检查 package.json 中的依赖
+- 从 .nvmrc 或 package.json engines 记录运行时版本
+- 仅包含影响理解的依赖（不是每个工具库）
+- 仅在版本重要时指定版本（破坏性变更、兼容性）
+
+**在阶段规划中的用途：**
+- 添加新依赖时（检查兼容性）
+- 升级框架时（了解当前使用情况）
+- 选择实现方法时（必须与现有技术栈兼容）
+- 了解构建要求
+</guidelines>

package/.opencode/templates/codebase/structure.md

@@ -0,0 +1,285 @@
+# 结构模板
+
+`.planning/codebase/STRUCTURE.md` 的模板 - 记录物理文件组织。
+
+**用途：** 记录代码库中各部分的物理位置。回答"X 应该放在哪里？"
+
+---
+
+## 文件模板
+
+```markdown
+# 代码库结构
+
+**分析日期：** [YYYY-MM-DD]
+
+## 目录布局
+
+[使用 ASCII 方框绘制字符展示顶层目录及其用途的树形图 - 仅使用 ├── └── │ 字符绘制树形结构]
+
+```
+[project-root]/
+├── [dir]/          # [用途]
+├── [dir]/          # [用途]
+├── [dir]/          # [用途]
+└── [file]          # [用途]
+```
+
+## 目录用途
+
+**[目录名]：**
+- 用途：[存放什么]
+- 包含：[文件类型：例如 "*.ts 源文件"、"组件目录"]
+- 关键文件：[此目录中的重要文件]
+- 子目录：[如有嵌套，描述结构]
+
+**[目录名]：**
+- 用途：[存放什么]
+- 包含：[文件类型]
+- 关键文件：[重要文件]
+- 子目录：[结构]
+
+## 关键文件位置
+
+**入口点：**
+- [路径]：[用途：例如 "CLI 入口点"]
+- [路径]：[用途：例如 "服务器启动"]
+
+**配置：**
+- [路径]：[用途：例如 "TypeScript 配置"]
+- [路径]：[用途：例如 "构建配置"]
+- [路径]：[用途：例如 "环境变量"]
+
+**核心逻辑：**
+- [路径]：[用途：例如 "业务服务"]
+- [路径]：[用途：例如 "数据库模型"]
+- [路径]：[用途：例如 "API 路由"]
+
+**测试：**
+- [路径]：[用途：例如 "单元测试"]
+- [路径]：[用途：例如 "测试固定数据"]
+
+**文档：**
+- [路径]：[用途：例如 "面向用户的文档"]
+- [路径]：[用途：例如 "开发者指南"]
+
+## 命名规范
+
+**文件：**
+- [模式]：[示例：例如 "模块使用 kebab-case.ts"]
+- [模式]：[示例：例如 "React 组件使用 PascalCase.tsx"]
+- [模式]：[示例：例如 "测试文件使用 *.test.ts"]
+
+**目录：**
+- [模式]：[示例：例如 "功能目录使用 kebab-case"]
+- [模式]：[示例：例如 "集合使用复数名称"]
+
+**特殊模式：**
+- [模式]：[示例：例如 "index.ts 用于目录导出"]
+- [模式]：[示例：例如 "__tests__ 用于测试目录"]
+
+## 新代码放置位置
+
+**新功能：**
+- 主要代码：[目录路径]
+- 测试：[目录路径]
+- 配置（如需要）：[目录路径]
+
+**新组件/模块：**
+- 实现：[目录路径]
+- 类型：[目录路径]
+- 测试：[目录路径]
+
+**新路由/命令：**
+- 定义：[目录路径]
+- 处理器：[目录路径]
+- 测试：[目录路径]
+
+**工具函数：**
+- 共享辅助函数：[目录路径]
+- 类型定义：[目录路径]
+
+## 特殊目录
+
+[任何有特殊含义或自动生成的目录]
+
+**[目录]：**
+- 用途：[例如 "生成的代码"、"构建输出"]
+- 来源：[例如 "由 X 自动生成"、"构建产物"]
+- 是否提交：[是/否 - 是否在 .gitignore 中？]
+
+---
+
+*结构分析：[date]*
+*目录结构变更时更新*
+```
+
+<good_examples>
+```markdown
+# 代码库结构
+
+**分析日期：** 2025-01-20
+
+## 目录布局
+
+```
+specops/
+├── bin/                # 可执行入口点
+├── commands/           # 斜杠命令定义
+│   └── specops/       # SpecOps 专用命令
+├── specops/           # 技能资源
+│   ├── references/    # 原则文档
+│   ├── templates/     # 文件模板
+│   └── workflows/     # 多步骤流程
+├── src/               # 源代码（如适用）
+├── tests/             # 测试文件
+├── package.json       # 项目清单
+└── README.md          # 用户文档
+```
+
+## 目录用途
+
+**bin/**
+- 用途：CLI 入口点
+- 包含：install.js（安装脚本）
+- 关键文件：install.js - 处理 npx 安装
+- 子目录：无
+
+**commands/specops/**
+- 用途：Claude Code 的斜杠命令定义
+- 包含：*.md 文件（每个命令一个）
+- 关键文件：new-project.md、plan-phase.md、execute-plan.md
+- 子目录：无（扁平结构）
+
+**specops/references/**
+- 用途：核心理念和指导文档
+- 包含：principles.md、questioning.md、plan-format.md
+- 关键文件：principles.md - 系统理念
+- 子目录：无
+
+**specops/templates/**
+- 用途：.planning/ 文件的文档模板
+- 包含：带前置元数据的模板定义
+- 关键文件：project.md、roadmap.md、plan.md、summary.md
+- 子目录：codebase/（新增 - 用于技术栈/架构/结构模板）
+
+**specops/workflows/**
+- 用途：可复用的多步骤流程
+- 包含：由命令调用的工作流定义
+- 关键文件：execute-plan.md、research-phase.md
+- 子目录：无
+
+## 关键文件位置
+
+**入口点：**
+- `bin/install.js` - 安装脚本（npx 入口）
+
+**配置：**
+- `package.json` - 项目元数据、依赖、bin 入口
+- `.gitignore` - 排除的文件
+
+**核心逻辑：**
+- `bin/install.js` - 所有安装逻辑（文件复制、路径替换）
+
+**测试：**
+- `tests/` - 测试文件（如存在）
+
+**文档：**
+- `README.md` - 面向用户的安装和使用指南
+- `CLAUDE.md` - 在此仓库中工作时给 Claude Code 的指令
+
+## 命名规范
+
+**文件：**
+- kebab-case.md：Markdown 文档
+- kebab-case.js：JavaScript 源文件
+- UPPERCASE.md：重要项目文件（README、CLAUDE、CHANGELOG）
+
+**目录：**
+- kebab-case：所有目录
+- 集合使用复数：templates/、commands/、workflows/
+
+**特殊模式：**
+- {command-name}.md：斜杠命令定义
+- *-template.md：可以使用但优先使用 templates/ 目录
+
+## 新代码放置位置
+
+**新斜杠命令：**
+- 主要代码：`commands/specops/{command-name}.md`
+- 测试：`tests/commands/{command-name}.test.js`（如已实现测试）
+- 文档：更新 `README.md` 中的新命令
+
+**新模板：**
+- 实现：`specops/templates/{name}.md`
+- 文档：模板自带文档（包含指南）
+
+**新工作流：**
+- 实现：`specops/workflows/{name}.md`
+- 用法：从命令中引用 `@.opencode/workflows/{name}.md`
+
+**新参考文档：**
+- 实现：`specops/references/{name}.md`
+- 用法：根据需要从命令/工作流中引用
+
+**工具函数：**
+- 尚无工具函数（`install.js` 是单体的）
+- 如需提取：`src/utils/`
+
+## 特殊目录
+
+**specops/**
+- 用途：安装到 .opencode/ 的资源
+- 来源：安装期间由 bin/install.js 复制
+- 是否提交：是（真实来源）
+
+**commands/**
+- 用途：安装到 .opencode/commands/ 的斜杠命令
+- 来源：安装期间由 bin/install.js 复制
+- 是否提交：是（真实来源）
+
+---
+
+*结构分析：2025-01-20*
+*目录结构变更时更新*
+```
+</good_examples>
+
+<guidelines>
+**STRUCTURE.md 中应包含的内容：**
+- 目录布局（使用 ASCII 方框绘制字符展示结构可视化）
+- 每个目录的用途
+- 关键文件位置（入口点、配置、核心逻辑）
+- 命名规范
+- 新代码放置位置（按类型）
+- 特殊/生成的目录
+
+**不应包含的内容：**
+- 概念架构（那是 ARCHITECTURE.md 的内容）
+- 技术栈（那是 STACK.md 的内容）
+- 代码实现细节（参考代码阅读）
+- 每一个文件（聚焦目录和关键文件）
+
+**填写此模板时：**
+- 使用 `tree -L 2` 或类似命令可视化结构
+- 识别顶层目录及其用途
+- 通过观察现有文件记录命名模式
+- 定位入口点、配置和主要逻辑区域
+- 目录树保持简洁（最多 2-3 层）
+
+**树形格式（仅使用 ASCII 方框绘制字符展示结构）：**
+```
+root/
+├── dir1/           # 用途
+│   ├── subdir/    # 用途
+│   └── file.ts    # 用途
+├── dir2/          # 用途
+└── file.ts        # 用途
+```
+
+**在阶段规划中的用途：**
+- 添加新功能时（文件应该放在哪里？）
+- 了解项目组织
+- 查找特定逻辑的位置
+- 遵循现有规范
+</guidelines>