diff --git a/.github/workflows/skill-review.yml b/.github/workflows/skill-review.yml new file mode 100644 index 0000000..aee21d6 --- /dev/null +++ b/.github/workflows/skill-review.yml @@ -0,0 +1,22 @@ +# Tessl Skill Review — runs on PRs that change any SKILL.md; posts scores as one PR comment. +# Docs: https://github.com/tesslio/skill-review +name: Tessl Skill Review + +on: + pull_request: + branches: [main] + paths: + - "**/SKILL.md" + +jobs: + review: + runs-on: ubuntu-latest + permissions: + pull-requests: write + contents: read + steps: + - uses: actions/checkout@v4 + - uses: tesslio/skill-review@main + # Optional quality gate (off by default — do not enable unless user asked): + # with: + # fail-threshold: 70 diff --git a/adk-skill-design-patterns-zh/skills/api-expert/SKILL.md b/adk-skill-design-patterns-zh/skills/api-expert/SKILL.md index 37589af..2a516bd 100755 --- a/adk-skill-design-patterns-zh/skills/api-expert/SKILL.md +++ b/adk-skill-design-patterns-zh/skills/api-expert/SKILL.md @@ -1,25 +1,35 @@ --- name: api-expert -description: FastAPI 开发最佳实践与约定。适用于编写、审查或排查 FastAPI 应用、REST API 或 Pydantic 模型时。 +description: "FastAPI 开发专家，提供路由设计、Pydantic 模型、依赖注入和中间件的最佳实践指导。Use when writing, reviewing, debugging, or refactoring FastAPI applications, REST API endpoints, or Pydantic data models." metadata: pattern: tool-wrapper domain: fastapi --- -你是一名 FastAPI 开发专家。请将这些约定应用到用户的代码或问题中。 - -## 核心约定 - -加载 `references/conventions.md`，查看完整的 FastAPI 最佳实践清单。 +你是一名 FastAPI 开发专家。请将 `references/conventions.md` 中的约定应用到用户的代码或问题中。 ## 审查代码时 -1. 加载约定文档 + +1. 加载 `references/conventions.md` 获取完整约定清单 2. 逐条检查用户代码是否符合约定 -3. 对每一处违规，引用具体规则并给出修改建议 +3. 对每一处违规，引用具体规则编号并给出修改建议，附上修正后的代码片段 4. 对符合最佳实践的写法给予肯定 +5. **验证点**：确认所有端点均有正确的 HTTP 状态码、类型标注和错误处理 ## 编写代码时 -1. 加载约定文档 + +1. 加载 `references/conventions.md` 获取完整约定清单 2. 严格遵守其中所有约定 3. 为所有函数签名补全类型标注 4. 使用 `Annotated` 风格进行依赖注入 +5. **验证点**：确认生成的代码包含路由装饰器类型标注、响应模型声明和异常处理 + +## 示例：端点审查输出格式 + +``` +❌ 规则 3 违规（第 15 行）：缺少响应模型声明 + 修改前：@app.get("/users") + 修改后：@app.get("/users", response_model=list[UserOut]) + +✅ 规则 7 已遵守：正确使用 Annotated[Session, Depends(get_db)] +``` diff --git a/adk-skill-design-patterns-zh/skills/code-reviewer/SKILL.md b/adk-skill-design-patterns-zh/skills/code-reviewer/SKILL.md index 5a59c97..022d3d6 100755 --- a/adk-skill-design-patterns-zh/skills/code-reviewer/SKILL.md +++ b/adk-skill-design-patterns-zh/skills/code-reviewer/SKILL.md @@ -1,25 +1,54 @@ --- name: code-reviewer -description: 审查 Python 代码的质量、风格和常见缺陷。适用于用户提交代码要求审查、希望获得反馈或进行代码审计时。 +description: "审查 Python 代码的质量、风格和常见缺陷，输出带严重程度分级的结构化审查报告。Use when the user submits Python code for review, requests feedback, performs a code audit, or asks to check code quality." metadata: pattern: reviewer severity-levels: error,warning,info --- -你是一名 Python 代码审查助手。请严格遵循以下审查流程： +你是一名 Python 代码审查助手。请严格遵循以下审查流程。 -第 1 步：加载 `references/review-checklist.md`，获取完整的审查标准。 +## 第 1 步：加载审查标准 -第 2 步：仔细阅读用户代码。在提出问题之前，先理解代码的用途。 +加载 `references/review-checklist.md`，获取完整的审查清单。 -第 3 步：对照清单中的每条规则审查代码。每发现一处问题： +## 第 2 步：理解代码意图 + +仔细阅读用户代码。在提出问题之前，先理解代码的用途和上下文。 + +## 第 3 步：逐条审查 + +对照清单中的每条规则审查代码。每发现一处问题： - 记录行号（或大致位置） - 标记严重程度：`error`（必须修复）、`warning`（建议修复）、`info`（可考虑优化） -- 说明为什么这是问题，而不只是指出问题是什么 +- 说明**为什么**这是问题，而不只是指出问题是什么 - 给出具体修复方案，并附上修正后的代码 -第 4 步：输出结构化审查结果，包含以下部分： -- **摘要**：代码的作用，以及整体质量判断（1-2 句话） -- **问题清单**：按严重程度分组（先 `error`，再 `warning`，最后 `info`） -- **评分**：按 1-10 分打分，并简要说明理由 -- **最值得优先处理的 3 条建议**：影响最大的改进项 +**验证点**：确认已检查清单中的所有规则，未遗漏任何类别。 + +## 第 4 步：输出结构化审查结果 + +按以下格式组织输出： + +```markdown +## 摘要 +[代码的作用，以及整体质量判断（1-2 句话）] + +## 问题清单 +### 🔴 Error（必须修复） +- **第 N 行**：[问题描述] → [修复方案] + +### 🟡 Warning（建议修复） +- **第 N 行**：[问题描述] → [修复方案] + +### 🔵 Info（可考虑优化） +- **第 N 行**：[问题描述] → [修复方案] + +## 评分：X/10 +[简要说明理由] + +## 最值得优先处理的 3 条建议 +1. [影响最大的改进项] +2. [次要改进项] +3. [第三改进项] +``` diff --git a/adk-skill-design-patterns-zh/skills/doc-pipeline/SKILL.md b/adk-skill-design-patterns-zh/skills/doc-pipeline/SKILL.md index a928212..41d6bcf 100755 --- a/adk-skill-design-patterns-zh/skills/doc-pipeline/SKILL.md +++ b/adk-skill-design-patterns-zh/skills/doc-pipeline/SKILL.md @@ -1,49 +1,51 @@ --- name: doc-pipeline -description: 通过多步骤流水线从 Python 源码生成 API 文档。适用于用户要求为模块编写文档、生成 API 文档或从代码创建说明文档时。 +description: “通过四步流水线从 Python 源码生成完整的 API 参考文档，包括解析、docstring 生成、文档组装和质量检查。Use when the user asks to generate API documentation, write docs for a Python module, or create reference documentation from source code.” metadata: pattern: pipeline - steps: "4" + steps: “4” --- -你正在执行一条文档生成流水线。请按顺序完成每一步。如果某一步失败，不要跳过，也不要继续往下执行。 +你正在执行一条文档生成流水线。请按顺序完成每一步。如果某一步失败，停止执行并报告错误原因。 ## 第 1 步 - 解析与盘点 分析用户的 Python 代码，并提取： -- 所有公开类及其方法 +- 所有公开类及其方法（排除 `_` 前缀的私有成员） - 所有公开函数 - 所有模块级常量 - 已有的 docstring（并标注哪些缺失） -将盘点结果以清单形式展示给用户，并询问：“这就是你想要文档化的完整公共 API 吗？” +将盘点结果以清单形式展示给用户，并询问：”这就是你想要文档化的完整公共 API 吗？” + +**验证点**：用户确认盘点结果后方可继续。 ## 第 2 步 - 生成 Docstring 对每一个缺少 docstring 的公开函数或方法： -- 加载 `references/docstring-style.md`，获取要求的格式 -- 严格按照风格规范生成 docstring -- 将生成的 docstring 展示给用户审批 +1. 加载 `references/docstring-style.md`，获取要求的格式 +2. 严格按照风格规范生成 docstring +3. 将生成的 docstring 展示给用户审批 -在用户确认这些 docstring 之前，不要进入第 3 步。 +**验证点**：用户确认所有 docstring 后方可进入第 3 步。 ## 第 3 步 - 组装文档 -加载 `assets/api-doc-template.md`，作为输出结构。 - -按照模板，将所有类、函数及其 docstring 汇编成一份 API 参考文档。 +1. 加载 `assets/api-doc-template.md`，作为输出结构 +2. 按照模板，将所有类、函数及其 docstring 汇编成一份 API 参考文档 +3. 文档必须包含： + - 带锚点链接的目录 + - 每个类或函数各自独立的小节 + - 每项对应的参数、返回类型和使用示例 -文档应包含： -- 带锚点链接的目录 -- 每个类或函数各自独立的小节 -- 每项对应的参数、返回类型和使用示例 +**验证点**：确认模板中所有章节均已填写，无空白占位。 ## 第 4 步 - 质量检查 对照 `references/quality-checklist.md` 审查最终文档： -- 每个公开符号都已经写入文档 -- 每个参数都有类型和说明 -- 每个函数至少包含一个使用示例 -- 文中不再残留占位文本 +- [ ] 每个公开符号都已经写入文档 +- [ ] 每个参数都有类型和说明 +- [ ] 每个函数至少包含一个使用示例 +- [ ] 文中不再残留占位文本 报告质量检查结果。如果发现问题，先修复，再展示最终文档。 diff --git a/adk-skill-design-patterns-zh/skills/project-planner/SKILL.md b/adk-skill-design-patterns-zh/skills/project-planner/SKILL.md index 3a272ef..d069989 100755 --- a/adk-skill-design-patterns-zh/skills/project-planner/SKILL.md +++ b/adk-skill-design-patterns-zh/skills/project-planner/SKILL.md @@ -1,6 +1,6 @@ --- name: project-planner -description: 先通过结构化提问收集需求，再输出软件项目规划。适用于用户说“我想做……”“帮我规划……”“设计一个系统”或“启动一个新项目”时。 +description: “通过结构化需求访谈收集信息，输出包含架构设计、技术选型和里程碑的软件项目规划文档。Use when the user says '我想做', '帮我规划', '设计一个系统', '启动一个新项目', or asks to plan, architect, or scope a software project.” metadata: pattern: inversion interaction: multi-turn @@ -8,24 +8,30 @@ metadata: 你正在进行一场结构化需求访谈。在所有阶段完成之前，不要开始构建或设计。 -## 第一阶段 - 问题发现（一次只问一个问题，并等待用户回答） +## 第一阶段 - 问题发现 -请按顺序提出以下问题，不要跳过。 +一次只问一个问题，等待用户回答后再继续。请按顺序提出，不要跳过。 -- Q1: “这个项目要为用户解决什么问题？” -- Q2: “主要用户是谁？他们的技术水平如何？” -- Q3: “预期规模有多大？（例如日活、数据量、请求量）” +1. Q1: “这个项目要为用户解决什么问题？” +2. Q2: “主要用户是谁？他们的技术水平如何？” +3. Q3: “预期规模有多大？（例如日活、数据量、请求量）” -## 第二阶段 - 技术约束（只有在第一阶段全部回答完后才进入） +**验证点**：确认 Q1-Q3 均已获得回答后方可进入第二阶段。 -- Q4: “你计划使用什么部署环境？（云平台、本地部署、Serverless 等）” -- Q5: “你是否有指定的技术栈要求或偏好？（语言、框架、数据库）” -- Q6: “有哪些不可妥协的要求？（延迟、可用性、合规、预算）” +## 第二阶段 - 技术约束 -## 第三阶段 - 综合整理（只有在所有问题都回答完后才进入） +4. Q4: “你计划使用什么部署环境？（云平台、本地部署、Serverless 等）” +5. Q5: “你是否有指定的技术栈要求或偏好？（语言、框架、数据库）” +6. Q6: “有哪些不可妥协的要求？（延迟、可用性、合规、预算）” + +**验证点**：确认 Q4-Q6 均已获得回答后方可进入第三阶段。 + +## 第三阶段 - 综合整理 1. 加载 `assets/plan-template.md`，作为输出格式 2. 使用收集到的需求填写模板中的每一个部分 3. 将完整方案展示给用户 -4. 询问：“这个方案是否准确反映了你的需求？你想改哪些地方？” +4. 询问：”这个方案是否准确反映了你的需求？你想改哪些地方？” 5. 根据反馈持续迭代，直到用户确认 + +**验证点**：用户明确确认方案后，流程结束。 diff --git a/adk-skill-design-patterns-zh/skills/report-generator/SKILL.md b/adk-skill-design-patterns-zh/skills/report-generator/SKILL.md index 14792b5..d0a2196 100755 --- a/adk-skill-design-patterns-zh/skills/report-generator/SKILL.md +++ b/adk-skill-design-patterns-zh/skills/report-generator/SKILL.md @@ -1,22 +1,36 @@ --- name: report-generator -description: 生成结构化技术报告（Markdown）。适用于用户要求撰写、创建或起草报告、总结或分析文档时。 +description: "按照风格指南和模板生成结构化的 Markdown 技术报告，支持技术、管理层和普通读者三种受众。Use when the user asks to write, create, draft, or generate a report, summary, analysis document, or technical write-up." metadata: pattern: generator output-format: markdown --- -你是一名技术报告生成助手。请严格按以下步骤执行： +你是一名技术报告生成助手。请严格按以下步骤执行。 -第 1 步：加载 `references/style-guide.md`，获取语气和格式规范。 +## 第 1 步：加载规范 -第 2 步：加载 `assets/report-template.md`，获取要求的输出结构。 +1. 加载 `references/style-guide.md`，获取语气和格式规范 +2. 加载 `assets/report-template.md`，获取要求的输出结构 -第 3 步：向用户询问填充模板所需的缺失信息： -- 主题或对象 -- 关键结论或数据点 -- 目标读者（技术、管理层、普通读者） +## 第 2 步：收集必要信息 -第 4 步：按照风格指南填写模板。输出中必须包含模板中的每一个部分。 +向用户询问填充模板所需的缺失信息： +- **主题或对象**：报告涵盖什么内容？ +- **关键结论或数据点**：需要包含哪些核心发现？ +- **目标读者**：技术人员、管理层还是普通读者？ -第 5 步：将完整报告作为单个 Markdown 文档返回。 +**验证点**：确认以上三项信息均已获取后方可继续。 + +## 第 3 步：填写模板 + +按照风格指南填写模板中的每一个部分。确保： +- 模板中所有章节均已填写，无空白占位 +- 语气和格式符合 `references/style-guide.md` 的要求 +- 根据目标读者调整技术细节的深度 + +## 第 4 步：输出与验证 + +将完整报告作为单个 Markdown 文档返回。 + +**验证点**：确认输出包含模板要求的全部章节，且无占位文本残留。 diff --git a/ruoyi-code-generator/SKILL.md b/ruoyi-code-generator/SKILL.md index 497f336..349983c 100644 --- a/ruoyi-code-generator/SKILL.md +++ b/ruoyi-code-generator/SKILL.md @@ -1,232 +1,140 @@ --- name: ruoyi-code-generator -description: | - 基于若依(RuoYi)框架规范生成 CRUD 代码。当用户需要为数据表生成后端Java代码（实体类、Mapper、Service、Controller）、 - 前端Vue代码（列表页、API封装）、MyBatis XML映射文件或菜单初始化SQL时使用此技能。 - 适用于: 创建新模块、添加业务功能、根据表结构生成代码等场景。 +description: "基于若依(RuoYi-Vue v3.9.x)框架规范，从数据表定义生成完整 CRUD 代码（Java Domain/Mapper/Service/Controller、MyBatis XML、Vue 2 页面与 API、菜单 SQL）。Use when the user needs to generate RuoYi code, scaffold a CRUD module, create backend and frontend from a database table, or add a new business module to a RuoYi-Vue project." --- # RuoYi 代码生成器技能 -## 📌 目标 (Goal) +## 目标 -根据用户提供的数据表信息（表名、字段定义），按照若依框架规范自动生成完整的 CRUD 代码，包括： -- Java 后端代码（Domain、Mapper、Service、ServiceImpl、Controller） +根据用户提供的数据表信息（表名、字段定义），按照若依框架规范生成完整 CRUD 代码。 + +**输出文件：** +- Java 后端：Domain、Mapper、Service、ServiceImpl、Controller - MyBatis XML 映射文件 -- Vue 前端代码（页面组件、API 封装） +- Vue 前端：页面组件 + API 封装 - 菜单初始化 SQL --- -## 📥 输入定义 (Input) - -用户需要提供以下信息（可以通过对话澄清获取）： +## 输入参数 | 参数 | 必填 | 说明 | 示例 | |------|------|------|------| -| `tableName` | ✅ | 数据库表名 | `sys_product` | -| `tableComment` | ✅ | 表注释/功能名称 | `产品管理` | -| `columns` | ✅ | 字段列表（含类型、注释） | 见下方示例 | -| `packageName` | ❌ | 包路径，默认 `com.ruoyi.system` | `com.ruoyi.business` | -| `moduleName` | ❌ | 模块名，默认取表前缀后的名称 | `product` | -| `businessName` | ❌ | 业务名称，默认取表名去前缀 | `product` | -| `author` | ❌ | 作者名，默认 `ruoyi` | `zhangsan` | -| `tplCategory` | ❌ | 模板类型: `crud`/`tree`/`sub`，默认 `crud` | `crud` | - -### 字段定义示例 - -```json -{ - "tableName": "sys_product", - "tableComment": "产品管理", - "columns": [ - {"name": "product_id", "type": "bigint", "comment": "产品ID", "isPk": true, "isIncrement": true}, - {"name": "product_name", "type": "varchar(100)", "comment": "产品名称", "isRequired": true, "isQuery": true}, - {"name": "product_code", "type": "varchar(50)", "comment": "产品编码", "isRequired": true}, - {"name": "category_id", "type": "bigint", "comment": "分类ID", "dictType": "product_category"}, - {"name": "price", "type": "decimal(10,2)", "comment": "价格"}, - {"name": "status", "type": "char(1)", "comment": "状态（0正常 1停用）", "dictType": "sys_normal_disable"}, - {"name": "create_time", "type": "datetime", "comment": "创建时间"} - ] -} -``` - ---- - -## 📤 输出定义 (Output) - -生成以下文件结构的代码： - -``` -输出文件清单: -├── java/ -│ ├── domain/{ClassName}.java # 实体类 -│ ├── mapper/{ClassName}Mapper.java # Mapper接口 -│ ├── service/I{ClassName}Service.java # Service接口 -│ ├── service/impl/{ClassName}ServiceImpl.java # Service实现 -│ └── controller/{ClassName}Controller.java # REST控制器 -├── xml/ -│ └── {ClassName}Mapper.xml # MyBatis映射文件 -├── vue/ -│ ├── api/{businessName}.js # API封装 -│ └── views/{moduleName}/{businessName}/index.vue # 页面组件 -└── sql/ - └── {businessName}Menu.sql # 菜单初始化SQL -``` +| `tableName` | 是 | 数据库表名 | `sys_product` | +| `tableComment` | 是 | 表注释/功能名称 | `产品管理` | +| `columns` | 是 | 字段列表（含类型、注释） | 见 [references/examples.md](references/examples.md) | +| `packageName` | 否 | 包路径，默认 `com.ruoyi.system` | `com.ruoyi.business` | +| `moduleName` | 否 | 模块名，默认取表前缀后的名称 | `product` | +| `businessName` | 否 | 业务名称，默认取表名去前缀 | `product` | +| `author` | 否 | 作者名，默认 `ruoyi` | `zhangsan` | +| `tplCategory` | 否 | 模板类型: `crud`/`tree`/`sub`，默认 `crud` | `crud` | --- -## 📋 执行流程 (Workflow) +## 执行流程 -### 第一步：信息收集与验证 +### 1. 信息收集与验证 -1. **解析用户请求**：识别表名、字段信息 -2. **缺省信息追问**：如果缺少必要信息，主动询问用户 -3. **推断默认值**： +1. 解析用户请求，识别表名与字段信息。 +2. 如果缺少必填参数（`tableName`、`tableComment`、`columns`），主动询问用户。 +3. 推断默认值： - `className` = 表名转大驼峰（去除表前缀如 `sys_`） - `moduleName` = 表前缀后的模块名 - `businessName` = 表名去前缀后的小写形式 - - 主键字段 = 字段中 `isPk=true` 的字段，默认为 `{tableName}_id` + - 主键字段 = `isPk=true` 的字段，默认为 `{tableName}_id` +4. **验证检查点**：向用户确认推断的类名、模块名、包路径是否正确，再继续。 -### 第二步：变量准备 +### 2. 变量准备 -根据输入计算所有模板变量： +根据输入计算所有模板变量（`${ClassName}`, `${className}`, `${moduleName}`, `${businessName}`, `${packageName}`, `${permissionPrefix}` 等）。 -``` -核心变量: -- ${tableName} 表名 -- ${tableComment} 表注释 -- ${ClassName} 类名(大驼峰) -- ${className} 类名(小驼峰) -- ${moduleName} 模块名 -- ${businessName} 业务名 -- ${BusinessName} 业务名(首字母大写) -- ${packageName} 包路径 -- ${author} 作者 -- ${datetime} 生成日期 -- ${pkColumn} 主键字段信息 -- ${columns} 所有字段列表 -- ${permissionPrefix} 权限前缀 (格式: moduleName:businessName) -``` - -### 第三步：代码生成 +完整变量清单参见 [references/coding-standards.md](references/coding-standards.md)。 -按顺序读取并填充模板： +### 3. 代码生成 -1. **读取模板文件**：从 `templates/` 目录加载对应模板 -2. **变量替换**：将 `${变量名}` 替换为实际值 -3. **条件处理**：根据字段配置处理 `#if/#foreach` 逻辑 -4. **输出代码**：生成最终代码文件 +按顺序读取 `templates/` 目录中的 Velocity 模板并填充： -### 第四步：自检与交付 +1. **Java 后端** — `templates/java/*.vm`：Domain → Mapper → Service → ServiceImpl → Controller +2. **MyBatis XML** — `templates/xml/mapper.xml.vm` +3. **Vue 前端** — `templates/vue/index.vue.vm` + `templates/js/api.js.vm` +4. **菜单 SQL** — `templates/sql/sql.vm` -1. **代码审查**：检查生成的代码是否符合规范 -2. **依赖提示**：告知用户需要添加的依赖或配置 -3. **使用说明**：提供后续操作指引 +对每个生成文件执行变量替换（`${变量名}` → 实际值）和条件/循环处理（`#if`/`#foreach`）。 ---- +### 4. 自检与交付 -## ⚠️ 约束条件 (Constraints) - -1. **命名规范**： - - 类名必须使用大驼峰 (PascalCase) - - 变量名必须使用小驼峰 (camelCase) - - 包路径必须全小写 - -2. **编码规范**： - - Java 文件使用 UTF-8 编码 - - 缩进使用 4 个空格 - - 必须包含完整的 Javadoc 注释 - -3. **安全规范**： - - Controller 必须添加 `@PreAuthorize` 权限注解 - - 删除操作必须添加 `@Log` 日志注解 - - 敏感字段（如密码）不出现在列表展示中 - -4. **禁止事项**： - - ❌ 不生成测试类（如需要请单独请求） - - ❌ 不修改已存在的文件（除非用户明确要求） - - ❌ 不硬编码任何敏感信息 +1. **编译验证**：检查生成的 Java 代码包路径、import 语句、注解是否完整。 +2. **安全检查**：确认 Controller 包含 `@PreAuthorize` 权限注解，删除操作包含 `@Log`。 +3. **依赖提示**：告知用户需要在 `pom.xml` 或路由配置中添加的内容。 +4. **验证检查点**：列出所有生成的文件路径，供用户确认。 --- -## 🔧 字段类型映射 +## 约束条件 -| 数据库类型 | Java类型 | 说明 | -|-----------|---------|------| -| `bigint` | `Long` | 长整型 | -| `int/integer` | `Integer` | 整型 | -| `varchar/char/text` | `String` | 字符串 | -| `datetime/timestamp` | `Date` | 日期时间 | -| `date` | `Date` | 日期 | -| `decimal/numeric` | `BigDecimal` | 高精度数值 | -| `float/double` | `Double` | 浮点数 | -| `tinyint(1)/bit` | `Boolean` | 布尔值 | +**命名规范：** +- 类名：大驼峰 (PascalCase)；变量名：小驼峰 (camelCase)；包路径：全小写 ---- +**编码规范：** +- UTF-8 编码，4 空格缩进，完整 Javadoc 注释 -## 📁 模板引用 +**安全规范：** +- Controller 必须添加 `@PreAuthorize` 权限注解 +- 删除操作必须添加 `@Log` 日志注解 +- 敏感字段（如密码）不出现在列表展示中 -生成代码时，请参考以下模板文件： +**禁止事项：** +- 不生成测试类（如需要请单独请求） +- 不修改已存在的文件（除非用户明确要求） +- 不硬编码任何敏感信息 -- **Java 模板**: `templates/java/` 目录下的 `.vm` 文件 -- **Vue 模板**: `templates/vue/` 目录下的 `.vm` 文件 -- **XML 模板**: `templates/xml/` 目录下的 `.vm` 文件 -- **SQL 模板**: `templates/sql/` 目录下的 `.vm` 文件 +字段类型映射与编码标准详见 [references/coding-standards.md](references/coding-standards.md)。 --- -## 💡 使用示例 - -### 示例对话 1：基础生成 +## 模板引用 -**用户**: 帮我生成一个产品管理模块的代码，表名是 sys_product +| 类别 | 路径 | 说明 | +|------|------|------| +| Java | `templates/java/*.vm` | Domain、Mapper、Service、ServiceImpl、Controller | +| Vue | `templates/vue/index.vue.vm` | 列表页面组件 | +| JS | `templates/js/api.js.vm` | API 封装 | +| XML | `templates/xml/mapper.xml.vm` | MyBatis 映射文件 | +| SQL | `templates/sql/sql.vm` | 菜单初始化 SQL | -**Agent 响应**: -1. 首先确认字段信息 -2. 推断默认配置 -3. 生成完整代码 -4. 提供使用说明 +--- -### 示例对话 2：指定配置 +## 示例 -**用户**: +**用户输入：** ``` 生成代码: - 表名: biz_order -- 功能: 订单管理 +- 功能: 订单管理 - 包路径: com.ruoyi.business -- 字段: order_id(主键), order_no(订单号), customer_name(客户名), amount(金额), status(状态), create_time(创建时间) +- 字段: order_id(bigint,主键), order_no(varchar(50),订单号), customer_name(varchar(100),客户名), amount(decimal(10,2),金额), status(char(1),状态), create_time(datetime,创建时间) ``` -**Agent 响应**: +**生成结果：** ``` -已为您生成订单管理模块代码，包含以下文件： - -Java后端: -- Order.java (实体类) -- OrderMapper.java (Mapper接口) -- IOrderService.java (Service接口) -- OrderServiceImpl.java (Service实现) -- OrderController.java (控制器) - -MyBatis: -- OrderMapper.xml (映射文件) - -Vue前端: -- order.js (API封装) -- index.vue (列表页面) - -SQL脚本: -- orderMenu.sql (菜单初始化) - -[具体代码内容...] +java/domain/Order.java +java/mapper/OrderMapper.java +java/service/IOrderService.java +java/service/impl/OrderServiceImpl.java +java/controller/OrderController.java +xml/OrderMapper.xml +vue/api/order.js +vue/views/order/order/index.vue +sql/orderMenu.sql ``` +更多示例见 [references/examples.md](references/examples.md)。 + --- -## 🔄 版本说明 +## 版本兼容 -- **兼容版本**: RuoYi-Vue v3.9.x -- **前端框架**: Vue 2 + Element UI -- **后端框架**: Spring Boot 2.x + MyBatis +- **RuoYi-Vue**: v3.9.x +- **前端**: Vue 2 + Element UI +- **后端**: Spring Boot 2.x + MyBatis diff --git a/spec-architect/SKILL.md b/spec-architect/SKILL.md index 36c0dde..c2f0df2 100644 --- a/spec-architect/SKILL.md +++ b/spec-architect/SKILL.md @@ -1,46 +1,86 @@ --- name: spec-architect -description: 专业的系统架构师技能。用于将模糊的功能想法转化为通过审批的工程级文档（需求 -> 设计 -> 任务）。当用户想要“设计”、“规划”或“spec”新功能时激活。 +description: “专业的系统架构师技能，将模糊的功能想法通过三阶段流程（需求 → 设计 → 任务拆解）转化为通过审批的工程级文档。Use when the user wants to design a feature, write a spec, plan architecture, create a technical design document, or break down a feature into implementation tasks.” --- # Spec-Driven Development Architect ## Role + 你是一位严格的系统架构师。你的职责是执行 Spec 流程，拒绝随性编码 (Vibe Coding)。 + **核心原则**：在 `tasks.md` 获得用户批准前，**严禁**编写任何功能代码。 -## The Process -请依次执行以下阶段。**每完成一个阶段，必须暂停 (STOP) 并等待用户确认。** +--- + +## 执行流程 + +依次执行以下三个阶段。**每完成一个阶段，必须暂停 (STOP) 并等待用户确认后再继续。** + +### 1. Requirements（需求定义） + +**输出**: `.agent/specs/{feature_name}/requirements.md` -### Phase 1: Requirements (需求定义) -**目标**: 创建 `.agent/specs/{feature_name}/requirements.md` -**指令**: -1. 确定功能名称（kebab-case）。 -2. **读取模板**: 读取本技能目录下的 `resources/requirements_tpl.md` 文件。 -3. **生成文档**: 根据用户的想法填充该模板。保持模板的章节结构（背景、用户故事、EARS 验收标准）。 -4. **Action**: 询问用户：“需求文档已生成，请审核。是否可以进入设计阶段？” +1. 从用户描述中提取功能名称（kebab-case 格式）。 +2. 读取模板 [resources/requirements_tpl.md](resources/requirements_tpl.md)。 +3. 根据用户的想法填充模板，保持章节结构（背景、用户故事、EARS 验收标准）。 +4. **验证检查点**：确认文档包含至少一个用户故事和对应的验收标准。 +5. **暂停** — 询问用户：”需求文档已生成，请审核。是否可以进入设计阶段？” + +### 2. Design（架构设计） -### Phase 2: Design (架构设计) **前提**: 用户已批准 `requirements.md`。 -**目标**: 创建 `.agent/specs/{feature_name}/design.md` -**指令**: -1. 读取已批准的 `requirements.md`。 -2. **读取模板**: 读取本技能目录下的 `resources/design_tpl.md` 文件。 -3. **生成文档**: 填充模板，包含架构图 (Mermaid)、数据模型和 API 接口。 -4. **Action**: 询问用户：“设计文档已生成，请审核。是否可以制定实施计划？” - -### Phase 3: Planning (任务拆解) +**输出**: `.agent/specs/{feature_name}/design.md` + +1. 读取已批准的 `requirements.md`。 +2. 读取模板 [resources/design_tpl.md](resources/design_tpl.md)。 +3. 填充模板，包含： + - 架构图（Mermaid 格式） + - 数据模型定义 + - API 接口设计 +4. **验证检查点**：确认每个需求条目在设计中都有对应的实现方案。 +5. **暂停** — 询问用户：”设计文档已生成，请审核。是否可以制定实施计划？” + +### 3. Planning（任务拆解） + **前提**: 用户已批准 `design.md`。 -**目标**: 创建 `.agent/specs/{feature_name}/tasks.md` -**指令**: +**输出**: `.agent/specs/{feature_name}/tasks.md` + 1. 读取 `design.md`。 -2. 将设计拆解为原子化的编码任务。 -3. **格式强制要求**: - - 必须使用 Markdown Checkbox (`- [ ]`)。 - - 任务粒度：单次 Agent 对话可完成（例如 "实现 User 模型" 而非 "做后端"）。 - - 禁止包含非编码任务（如"部署"、"开会"）。 -4. **Action**: 告知用户：“计划已就绪。输入 `@tasks.md 执行任务1` 开始。” - -## Constraints -1. 所有输出文档必须使用**简体中文**。 -2. 严格遵守模板格式，不要随意删减章节。 \ No newline at end of file +2. 将设计拆解为原子化的编码任务，格式要求： + - 使用 Markdown Checkbox (`- [ ]`) + - 任务粒度：单次 Agent 对话可完成（例如 “实现 User 模型” 而非 “做后端”） + - 禁止包含非编码任务（如”部署”、”开会”） +3. **验证检查点**：确认每个设计模块至少有一个对应任务，且无遗漏。 +4. **暂停** — 告知用户：”计划已就绪。输入 `@tasks.md 执行任务1` 开始。” + +--- + +## 示例 + +**用户输入**: “我想给系统加一个用户邀请功能” + +**Phase 1 输出** (`.agent/specs/user-invitation/requirements.md`): +```markdown +## 背景 +系统需要支持现有用户邀请新用户注册... + +## 用户故事 +- 作为管理员，我希望通过邮箱邀请新用户，以便快速扩展团队。 + +## 验收标准 (EARS) +- 当管理员输入有效邮箱并点击”邀请”时，系统应发送包含注册链接的邀请邮件。 +- 邀请链接应在 72 小时后过期。 +``` + +**Phase 2 输出**: 包含 Mermaid 序列图、`invitation` 表结构、`POST /api/invitations` 接口定义。 + +**Phase 3 输出**: 原子化任务列表，如 `- [ ] 创建 invitation 表迁移` → `- [ ] 实现 InvitationService.create()` → `- [ ] 添加邮件发送集成`。 + +--- + +## 约束条件 + +1. 所有输出文档必须使用**简体中文**。 +2. 严格遵守模板格式，不要随意删减章节。 +3. 在 `tasks.md` 获得批准前，不输出任何功能实现代码。 \ No newline at end of file diff --git a/springboot-init/SKILL.md b/springboot-init/SKILL.md index 0631294..60e97d3 100644 --- a/springboot-init/SKILL.md +++ b/springboot-init/SKILL.md @@ -1,54 +1,61 @@ --- name: springboot-init -description: Define development specifications for Spring Boot monolithic projects, supporting multiple technology stack configurations. +description: “Scaffolds a Spring Boot 3.x monolithic project with enforced layered architecture — generates directory structure, pom.xml, application.yml, and base classes (BaseResponse, GlobalExceptionHandler, MybatisPlusConfig), enforces strict DTO/VO/Entity data flow, and provides module creation workflows with naming conventions. Use when setting up a new Spring Boot project, initializing a Java backend, scaffolding a Maven project with MyBatis-Plus, configuring Spring Boot 3.x dependencies, or adding a new CRUD module to an existing Spring Boot monolith.” --- + # springboot-init ## 目录 -1. [技术栈配置](#0-技术栈配置) | 2. [项目结构](#1-项目结构) | 3. [编码规范](#2-编码规范) | 4. [统一响应/异常](#3-统一响应规范) -5. [权限/工具/命名](#5-访问控制规范) | 6. [执行工作流](#6-执行工作流) | 7. [禁止事项](#7-禁止事项) | 8. [代码模板](#8-代码模板) +1. [技术栈](#1-技术栈配置) | 2. [项目结构](#2-项目结构与分层) | 3. [编码规范](#3-编码规范) | 4. [统一响应/异常](#4-统一响应与异常) +5. [访问控制/工具](#5-访问控制--工具库) | 6. [命名规范](#6-命名规范) | 7. [执行工作流](#7-执行工作流) | 8. [禁止事项](#8-禁止事项) | 9. [代码模板](#9-代码模板) --- -## 0. 技术栈配置 +## 1. 技术栈配置 -| 配置项 | 推荐选型 | 说明 | -| ---------- | ----------------------- | ------------------------------------------ | -| **JDK** | 17 / 21 | Spring Boot 3.x 必须 17+ | -| **ORM** | **MyBatis-Plus** (MP) | 默认选型，快速开发。追求极致性能选 Flex | -| **工具库** | **Hutool** / Guava | 减少重复轮子，增强开发效率 | -| **权限** | **Sa-Token** / Security | 快速开发选 Sa-Token，复杂企业级选 Security | +| 配置项 | 推荐选型 | 说明 | +|--------|---------|------| +| **JDK** | 17 / 21 | Spring Boot 3.x 必须 17+ | +| **ORM** | **MyBatis-Plus** (MP) | 默认选型，快速开发。追求极致性能选 Flex | +| **工具库** | **Hutool** / Guava | 减少重复轮子，增强开发效率 | +| **权限** | **Sa-Token** / Security | 快速开发选 Sa-Token，复杂企业级选 Security | --- -## 1. 项目结构与分层 +## 2. 项目结构与分层 -### 1.1 核心分层 -- **manager**: 仅当涉及“跨模块协调”或“第三方集成（OSS/短信）”时启用，避免直接耦合。 +### 2.1 核心分层 +- **manager**: 仅当涉及”跨模块协调”或”第三方集成（OSS/短信）”时启用，避免直接耦合。 - **common/config**: 存放 `BaseResponse`, `GlobalExceptionHandler`, `MybatisPlusConfig` 等。 -### 1.2 数据流向 (Strict) +### 2.2 数据流向（严格执行） + +``` +Controller ──DTO(Request)──▶ Service ──Entity──▶ Mapper/DB +Controller ◀──VO────────── Service ◀──Entity──── Mapper/DB +``` + - **DTO** (Request): `Controller` 输入专用。 - **VO**: `Controller` 输出专用。**严禁**将 `Entity` 直接返回前端。 - **Entity**: 与数据库表一一对应，仅在 `Service/Mapper` 层流通。 --- -## 2. 编码规范 +## 3. 编码规范 -### 2.1 Controller & Service +### 3.1 Controller & Service - **返回类型**：强制使用 `BaseResponse`。 - **参数校验**：多参数封装为对象，使用 `@RequestBody` + `Validation`。 - **Service**：业务逻辑收敛于此。MP 风格：`extends ServiceImpl implements Service`。 -### 2.2 Model (Entity/DTO/VO) +### 3.2 Model (Entity/DTO/VO) - **强制实现**：`Serializable` 并声明 `serialVersionUID`。 - **Java 17+**：优先使用 `record` 定义 DTO/VO。 - **MP 注解**：`@TableName`, `@TableId(type = IdType.ASSIGN_ID)`, `@TableLogic`。 --- -## 3. 统一响应与异常 +## 4. 统一响应与异常 - **ResultUtils**: 提供 `success(data)`, `error(errorCode, msg)`。 - **BusinessException**: 业务逻辑错误必须抛出此异常，由 `GlobalExceptionHandler` 统一捕获。 @@ -56,44 +63,71 @@ description: Define development specifications for Spring Boot monolithic projec --- -## 4. 访问控制 & 工具库 +## 5. 访问控制 & 工具库 -### 4.1 认证方案 +### 5.1 认证方案 - **Sa-Token**: 拦截器校验 `StpUtil.checkLogin()` 或 `@SaCheckRole`。 - **Spring Security**: `SecurityFilterChain` 配置及 `@PreAuthorize`。 -### 4.2 工具类推荐 (Hutool) +### 5.2 工具类推荐 (Hutool) - `StrUtil.isBlank`, `BeanUtil.copyProperties`, `JSONUtil.toJsonStr`, `SecureUtil.md5`。 --- -## 5. 命名规范 +## 6. 命名规范 -| 类型 | 模式 | 示例 | -| ---------- | ---------------------------- | ------------------ | -| Controller | `XxxController` | `UserController` | -| Service | `XxxService/Impl` | `UserServiceImpl` | -| DTO | `XxxAdd/Update/QueryRequest` | `UserQueryRequest` | -| VO | `XxxVO` | `UserVO` | -| DAO | `XxxMapper` | `UserMapper` | +| 类型 | 模式 | 示例 | +|------|------|------| +| Controller | `XxxController` | `UserController` | +| Service | `XxxService/Impl` | `UserServiceImpl` | +| DTO | `XxxAdd/Update/QueryRequest` | `UserQueryRequest` | +| VO | `XxxVO` | `UserVO` | +| DAO | `XxxMapper` | `UserMapper` | --- -## 6. 执行工作流 (Actionable Workflows) +## 7. 执行工作流 + +### 7.1 项目初始化 + +1. **确认配置**：向用户确认 `company`（groupId）、`project`（artifactId）、`jdk` 版本。 +2. **生成骨架**：创建目录树，生成 `pom.xml`、`application.yml`。 +3. **注入基础类**：生成 `common`、`exception`、`utils`、`config` 包内容（参见 [references/code-templates.md](references/code-templates.md)）。 +4. **验证检查点**：运行 `mvn compile`，确认骨架编译通过且无警告。 -### 6.1 项目初始化 -1. **确认配置**：识别 `company`, `project`, `jdk` 等变量。 -2. **生成骨架**：创建目录树，生成 `pom.xml`, `application.yml` (见 templates)。 -3. **注入基础类**：生成 `common`, `exception`, `utils`, `config` 包内容。 +### 7.2 模块新增 -### 6.2 模块新增 -1. **建模**：创建 Entity -> Mapper -> Service。 -2. **业务端点**：定义 Request/VO (Record) -> Controller 逻辑。 -3. **接口文档**：补充 Swagger 注解。 +1. **建模**：创建 Entity → Mapper → Service（含 `ServiceImpl`）。 +2. **业务端点**：定义 Request/VO（使用 `record`） → Controller 逻辑。 +3. **接口文档**：补充 Swagger/OpenAPI 注解。 +4. **验证检查点**：运行 `mvn compile` 并测试端点： + ```bash + curl -X POST http://localhost:8080/api//list \ + -H “Content-Type: application/json” \ + -d '{“current”: 1, “pageSize”: 10}' + ``` + +### 7.3 Controller 示例 + +```java +@RestController +@RequestMapping(“/api/user”) +public class UserController { + @Resource + private UserService userService; + + @PostMapping(“/list”) + public BaseResponse> listUsers(@RequestBody UserQueryRequest request) { + Page page = userService.listUsers(request); + return ResultUtils.success(page); + } +} +``` --- -## 7. 禁止事项 +## 8. 禁止事项 + 1. **禁止** 在 Controller 编写任何业务逻辑。 2. **禁止** Entity 跨过 Service 直接暴露给 Controller。 3. **禁止** 未经统一异常处理直接抛出原始 `Exception`。 @@ -101,6 +135,7 @@ description: Define development specifications for Spring Boot monolithic projec --- -## 8. 代码模板 +## 9. 代码模板 + 参考 [references/code-templates.md](references/code-templates.md)，包含： `BaseResponse`, `ErrorCode`, `BusinessException`, `GlobalExceptionHandler`, `ResultUtils`, `ThrowUtils`, `MybatisPlusConfig`, `JsonConfig`, `OpenApiConfig`。 diff --git a/superpowers-antigravity/skills/brainstorming/SKILL.md b/superpowers-antigravity/skills/brainstorming/SKILL.md index 2fd19ba..133341f 100644 --- a/superpowers-antigravity/skills/brainstorming/SKILL.md +++ b/superpowers-antigravity/skills/brainstorming/SKILL.md @@ -1,54 +1,84 @@ --- name: brainstorming -description: "You MUST use this before any creative work - creating features, building components, adding functionality, or modifying behavior. Explores user intent, requirements and design before implementation." +description: "Turns ideas into fully formed designs and specs through collaborative dialogue — asking one question at a time to refine intent, proposing multiple approaches with trade-offs, and presenting the design incrementally for validation. Use when starting any creative work such as creating features, building components, adding functionality, or modifying behavior before implementation begins." --- # Brainstorming Ideas Into Designs -## Overview +Turns ideas into fully formed designs through collaborative dialogue: understand context, refine intent with targeted questions, explore approaches, and present the design incrementally for validation. -Help turn ideas into fully formed designs and specs through natural collaborative dialogue. +## When to Use -Start by understanding the current project context, then ask questions one at a time to refine the idea. Once you understand what you're building, present the design in small sections (200-300 words), checking after each section whether it looks right so far. +- Starting a new feature, component, or significant behavior change +- Exploring an idea before committing to implementation +- Translating vague requirements into a concrete, actionable design +- Before using `superpowers:writing-plans` to create an implementation plan -## The Process +## Workflow -**Understanding the idea:** -- Check out the current project state first (files, docs, recent commits) -- Ask questions one at a time to refine the idea -- Prefer multiple choice questions when possible, but open-ended is fine too -- Only one question per message - if a topic needs more exploration, break it into multiple questions -- Focus on understanding: purpose, constraints, success criteria +### 1. Understand the Project Context +- Read relevant files, docs, and recent commits +- Identify existing patterns, constraints, and conventions +- **Validation:** Confirm you can describe the current state of the area being changed -**Exploring approaches:** -- Propose 2-3 different approaches with trade-offs -- Present options conversationally with your recommendation and reasoning +### 2. Refine the Idea Through Questions +- Ask **one question per message** — never batch multiple questions +- Prefer **multiple choice** questions when possible (easier to answer) +- Focus on: purpose, constraints, success criteria, edge cases +- Continue until you can articulate what is being built and why + +### 3. Explore Approaches +- Propose **2-3 approaches** with clear trade-offs - Lead with your recommended option and explain why +- Wait for confirmation before proceeding to design -**Presenting the design:** -- Once you believe you understand what you're building, present the design -- Break it into sections of 200-300 words -- Ask after each section whether it looks right so far +### 4. Present the Design Incrementally +- Break the design into sections of **200-300 words** +- After each section, ask: "Does this look right so far?" - Cover: architecture, components, data flow, error handling, testing -- Be ready to go back and clarify if something doesn't make sense - -## After the Design +- Revise any section based on feedback before continuing -**Documentation:** +### 5. Document the Design - Write the validated design to `docs/plans/YYYY-MM-DD--design.md` -- Use elements-of-style:writing-clearly-and-concisely skill if available +- Use `elements-of-style:writing-clearly-and-concisely` skill if available - Commit the design document to git -**Implementation (if continuing):** +### 6. Transition to Implementation (Optional) - Ask: "Ready to set up for implementation?" -- Use superpowers:using-git-worktrees to create isolated workspace -- Use superpowers:writing-plans to create detailed implementation plan +- Use `superpowers:using-git-worktrees` to create an isolated workspace +- Use `superpowers:writing-plans` to create a detailed implementation plan + +## Example + +``` +User: "I want to add notifications to the app" + +[Step 1: Read existing code, find no notification system exists] + +You: "What kind of events should trigger a notification? + A) User actions (comments, mentions, assignments) + B) System events (deploys, failures, thresholds) + C) Both" + +User: "A — just user actions for now" + +You: "Should notifications be real-time (WebSocket) or polled? + A) Real-time push + B) Poll every N seconds + C) Start with polling, migrate to real-time later" + +User: "C" + +[Step 3: Present 2 approaches — event bus vs direct insertion] +[Step 4: Present design in sections, validate each] +[Step 5: Write to docs/plans/2025-03-25-notifications-design.md] +``` ## Key Principles -- **One question at a time** - Don't overwhelm with multiple questions -- **Multiple choice preferred** - Easier to answer than open-ended when possible -- **YAGNI ruthlessly** - Remove unnecessary features from all designs -- **Explore alternatives** - Always propose 2-3 approaches before settling -- **Incremental validation** - Present design in sections, validate each -- **Be flexible** - Go back and clarify when something doesn't make sense +- **One question at a time** — do not overwhelm with multiple questions +- **Multiple choice preferred** — easier to answer than open-ended +- **YAGNI ruthlessly** — remove unnecessary features from all designs +- **Explore alternatives** — always propose 2-3 approaches before settling +- **Incremental validation** — present design in sections, validate each +- **Be flexible** — go back and clarify when something does not make sense diff --git a/superpowers-antigravity/skills/dispatching-parallel-agents/SKILL.md b/superpowers-antigravity/skills/dispatching-parallel-agents/SKILL.md index 33b1485..694ebba 100644 --- a/superpowers-antigravity/skills/dispatching-parallel-agents/SKILL.md +++ b/superpowers-antigravity/skills/dispatching-parallel-agents/SKILL.md @@ -1,6 +1,6 @@ --- name: dispatching-parallel-agents -description: Use when facing 2+ independent tasks that can be worked on without shared state or sequential dependencies +description: "Dispatches one subagent per independent problem domain to investigate and fix multiple unrelated failures concurrently — grouping by subsystem, creating focused prompts with specific scope and constraints, and integrating results after parallel execution. Use when facing 2+ independent failures across different test files or subsystems that share no state, or when multiple bugs can be investigated without sequential dependencies." --- # Dispatching Parallel Agents @@ -46,20 +46,24 @@ digraph when_to_use { ### 1. Identify Independent Domains -Group failures by what's broken: +Group failures by what is broken: - File A tests: Tool approval flow - File B tests: Batch completion behavior - File C tests: Abort functionality -Each domain is independent - fixing tool approval doesn't affect abort tests. +Each domain is independent — fixing tool approval does not affect abort tests. + +**Validation:** No two domains share mutable state or edit the same files. ### 2. Create Focused Agent Tasks Each agent gets: - **Specific scope:** One test file or subsystem - **Clear goal:** Make these tests pass -- **Constraints:** Don't change other code -- **Expected output:** Summary of what you found and fixed +- **Constraints:** Do not change other code +- **Expected output:** Summary of what was found and fixed + +**Validation:** Each prompt is self-contained — an agent can execute it without context from other prompts. ### 3. Dispatch in Parallel @@ -74,10 +78,12 @@ Task("Fix tool-approval-race-conditions.test.ts failures") ### 4. Review and Integrate When agents return: -- Read each summary -- Verify fixes don't conflict -- Run full test suite -- Integrate all changes +1. Read each summary +2. Verify fixes do not conflict (no overlapping file edits) +3. Run full test suite +4. Integrate all changes + +**Validation:** Full test suite passes with all agent changes combined. ## Agent Prompt Structure diff --git a/superpowers-antigravity/skills/executing-plans/SKILL.md b/superpowers-antigravity/skills/executing-plans/SKILL.md index ca77290..a68e878 100644 --- a/superpowers-antigravity/skills/executing-plans/SKILL.md +++ b/superpowers-antigravity/skills/executing-plans/SKILL.md @@ -1,76 +1,103 @@ --- name: executing-plans -description: Use when you have a written implementation plan to execute in a separate session with review checkpoints +description: "Loads a written implementation plan and executes it in batches of three tasks with architect review checkpoints between each batch — reviewing the plan critically, following each step exactly, running verifications, and reporting progress. Use when you have a written implementation plan to execute in a separate session, need batch execution with human review gates, or are continuing work from a brainstorming or planning skill." --- # Executing Plans -## Overview +Loads an implementation plan and executes tasks in batches of three, pausing between batches for architect review and feedback before continuing. -Load plan, review critically, execute tasks in batches, report for review between batches. +**Announce at start:** "I'm using the executing-plans skill to implement this plan." -**Core principle:** Batch execution with checkpoints for architect review. +## When to Use + +- A written implementation plan exists (from `superpowers:writing-plans` or similar) +- Tasks need human review checkpoints between batches +- Execution happens in a separate session from planning +- For same-session execution with subagents, use `superpowers:subagent-driven-development` instead + +## Workflow + +### 1. Load and Review Plan +- Read the plan file completely +- Review critically — identify questions, gaps, or concerns +- If concerns exist: raise them with human partner before starting +- If no concerns: create TodoWrite with all tasks and proceed +- **Validation:** Can articulate what each task requires and why + +### 2. Execute Batch (Default: 3 Tasks) +For each task in the batch: +1. Mark task as `in_progress` +2. Follow each step exactly as written in the plan +3. Run all verifications specified by the plan +4. Mark task as `completed` +- **Validation:** All verifications pass for every task in the batch + +### 3. Report and Wait +Present to human partner: +- What was implemented (per task) +- Verification output (test results, build status) +- Say: "Ready for feedback." +- **Do not proceed** until feedback is received -**Announce at start:** "I'm using the executing-plans skill to implement this plan." +### 4. Apply Feedback and Continue +- Apply any requested changes from feedback +- Execute the next batch of 3 tasks +- Repeat Steps 2-4 until all tasks are complete -## The Process +### 5. Complete Development +- Announce: "I'm using the finishing-a-development-branch skill to complete this work." +- **REQUIRED:** Use `superpowers:finishing-a-development-branch` +- Follow that skill to verify tests, present options, execute choice -### Step 1: Load and Review Plan -1. Read plan file -2. Review critically - identify any questions or concerns about the plan -3. If concerns: Raise them with your human partner before starting -4. If no concerns: Create TodoWrite and proceed +## Example -### Step 2: Execute Batch -**Default: First 3 tasks** +``` +[Plan: docs/plans/2025-03-20-auth-refactor.md with 7 tasks] -For each task: -1. Mark as in_progress -2. Follow each step exactly (plan has bite-sized steps) -3. Run verifications as specified -4. Mark as completed +Step 1: Read plan, no concerns, create TodoWrite -### Step 3: Report -When batch complete: -- Show what was implemented -- Show verification output -- Say: "Ready for feedback." +Step 2: Execute Batch 1 (Tasks 1-3) + Task 1: Extract auth middleware → done, tests pass + Task 2: Add token refresh logic → done, tests pass + Task 3: Update route guards → done, tests pass -### Step 4: Continue -Based on feedback: -- Apply changes if needed -- Execute next batch -- Repeat until complete +Step 3: Report + "Batch 1 complete. Extracted middleware, added refresh, updated guards. + All 12 tests passing. Ready for feedback." -### Step 5: Complete Development +Step 4: Partner says "Looks good, continue" -After all tasks complete and verified: -- Announce: "I'm using the finishing-a-development-branch skill to complete this work." -- **REQUIRED SUB-SKILL:** Use superpowers:finishing-a-development-branch -- Follow that skill to verify tests, present options, execute choice +Step 2: Execute Batch 2 (Tasks 4-6) + Task 5: Hit blocker — missing OAuth config + → STOP, ask: "Task 5 needs OAuth client ID. Where is this configured?" + +[Partner provides config location, continue] +... -## When to Stop and Ask for Help +Step 5: All tasks done → use finishing-a-development-branch +``` + +## When to Stop and Ask **STOP executing immediately when:** -- Hit a blocker mid-batch (missing dependency, test fails, instruction unclear) -- Plan has critical gaps preventing starting -- You don't understand an instruction +- Hit a blocker mid-batch (missing dependency, test failure, unclear instruction) +- Plan has critical gaps preventing progress +- An instruction is ambiguous - Verification fails repeatedly **Ask for clarification rather than guessing.** -## When to Revisit Earlier Steps - -**Return to Review (Step 1) when:** -- Partner updates the plan based on your feedback -- Fundamental approach needs rethinking +## Red Flags -**Don't force through blockers** - stop and ask. +**Never:** +- Skip verifications specified in the plan +- Continue past a batch without reporting and waiting for feedback +- Guess at unclear instructions instead of asking +- Force through blockers -## Remember -- Review plan critically first -- Follow plan steps exactly -- Don't skip verifications -- Reference skills when plan says to -- Between batches: just report and wait -- Stop when blocked, don't guess +**Always:** +- Review the plan critically before starting +- Follow plan steps exactly as written +- Reference sub-skills when the plan says to +- Stop when blocked diff --git a/superpowers-antigravity/skills/finishing-a-development-branch/SKILL.md b/superpowers-antigravity/skills/finishing-a-development-branch/SKILL.md index c308b43..52e408f 100644 --- a/superpowers-antigravity/skills/finishing-a-development-branch/SKILL.md +++ b/superpowers-antigravity/skills/finishing-a-development-branch/SKILL.md @@ -1,19 +1,23 @@ --- name: finishing-a-development-branch -description: Use when implementation is complete, all tests pass, and you need to decide how to integrate the work - guides completion of development work by presenting structured options for merge, PR, or cleanup +description: "Guides completion of development work by verifying tests pass, presenting four structured integration options (merge, PR, keep, discard), executing the chosen workflow, and cleaning up worktrees. Use when implementation is complete, all tests pass, and you need to decide how to integrate the work into the base branch." --- # Finishing a Development Branch -## Overview - -Guide completion of development work by presenting clear options and handling chosen workflow. +Guides completion of development work by presenting clear integration options and handling the chosen workflow including worktree cleanup. **Core principle:** Verify tests → Present options → Execute choice → Clean up. **Announce at start:** "I'm using the finishing-a-development-branch skill to complete this work." -## The Process +## When to Use + +- Implementation is complete and all tests pass +- Need to decide between merge, PR, keep, or discard for a feature branch +- Called by `superpowers:subagent-driven-development` (Step 7) or `superpowers:executing-plans` (Step 5) after all tasks complete + +## Workflow ### Step 1: Verify Tests diff --git a/superpowers-antigravity/skills/receiving-code-review/SKILL.md b/superpowers-antigravity/skills/receiving-code-review/SKILL.md index 5b21788..964c0d8 100644 --- a/superpowers-antigravity/skills/receiving-code-review/SKILL.md +++ b/superpowers-antigravity/skills/receiving-code-review/SKILL.md @@ -1,28 +1,29 @@ --- name: receiving-code-review -description: Use when receiving code review feedback, before implementing suggestions, especially if feedback seems unclear or technically questionable - requires technical rigor and verification, not performative agreement or blind implementation +description: "Evaluates code review feedback with technical rigor before implementing — restating requirements, verifying against the codebase, pushing back on incorrect suggestions, and implementing fixes one at a time with tests. Use when receiving code review feedback, before implementing reviewer suggestions, or when feedback seems unclear or technically questionable." --- # Code Review Reception -## Overview - -Code review requires technical evaluation, not emotional performance. +Evaluates code review feedback with technical rigor rather than performative agreement — verifying suggestions against codebase reality before implementing. **Core principle:** Verify before implementing. Ask before assuming. Technical correctness over social comfort. -## The Response Pattern +## When to Use -``` -WHEN receiving code review feedback: +- Received inline review comments or summary feedback on a PR +- A reviewer suggested changes that need technical evaluation +- Feedback seems unclear, incomplete, or technically questionable +- Multiple review items need triage and ordered implementation -1. READ: Complete feedback without reacting -2. UNDERSTAND: Restate requirement in own words (or ask) -3. VERIFY: Check against codebase reality -4. EVALUATE: Technically sound for THIS codebase? -5. RESPOND: Technical acknowledgment or reasoned pushback -6. IMPLEMENT: One item at a time, test each -``` +## Workflow + +### 1. Read — Complete feedback without reacting +### 2. Understand — Restate requirement in own words (or ask for clarification) +### 3. Verify — Check suggestion against codebase reality +### 4. Evaluate — Technically sound for THIS codebase? +### 5. Respond — Technical acknowledgment or reasoned pushback +### 6. Implement — One item at a time, test each ## Forbidden Responses diff --git a/superpowers-antigravity/skills/requesting-code-review/SKILL.md b/superpowers-antigravity/skills/requesting-code-review/SKILL.md index f0e3395..5650a74 100644 --- a/superpowers-antigravity/skills/requesting-code-review/SKILL.md +++ b/superpowers-antigravity/skills/requesting-code-review/SKILL.md @@ -1,93 +1,86 @@ --- name: requesting-code-review -description: Use when completing tasks, implementing major features, or before merging to verify work meets requirements +description: "Dispatches a code-reviewer subagent to evaluate recent changes against requirements — gathering git SHAs, filling the review prompt template, and triaging feedback by severity before proceeding. Use when completing tasks, implementing major features, before merging branches, or when stuck and needing a fresh perspective on code quality." --- # Requesting Code Review -Dispatch superpowers:code-reviewer subagent to catch issues before they cascade. +Dispatches a `superpowers:code-reviewer` subagent to catch issues before they cascade, using a structured prompt template with git SHAs and implementation context. -**Core principle:** Review early, review often. +## When to Use -## When to Request Review - -**Mandatory:** +**Mandatory triggers:** - After each task in subagent-driven development -- After completing major feature -- Before merge to main +- After completing a major feature +- Before merge to main/base branch **Optional but valuable:** - When stuck (fresh perspective) - Before refactoring (baseline check) -- After fixing complex bug +- After fixing a complex bug -## How to Request +## Workflow -**1. Get git SHAs:** +### 1. Capture Git SHAs ```bash -BASE_SHA=$(git rev-parse HEAD~1) # or origin/main +BASE_SHA=$(git rev-parse HEAD~1) # or origin/main for full branch diff HEAD_SHA=$(git rev-parse HEAD) ``` +**Validation:** Both SHAs resolve to valid commits + +### 2. Dispatch Code-Reviewer Subagent +Fill the prompt template at `./code-reviewer.md` with these placeholders: -**2. Dispatch code-reviewer subagent:** +| Placeholder | Value | +|---|---| +| `{WHAT_WAS_IMPLEMENTED}` | What was just built | +| `{PLAN_OR_REQUIREMENTS}` | What it should do (plan file or spec) | +| `{BASE_SHA}` | Starting commit | +| `{HEAD_SHA}` | Ending commit | +| `{DESCRIPTION}` | Brief summary of changes | -Use Task tool with superpowers:code-reviewer type, fill template at `code-reviewer.md` +Dispatch using the Task tool with `superpowers:code-reviewer` type. -**Placeholders:** -- `{WHAT_WAS_IMPLEMENTED}` - What you just built -- `{PLAN_OR_REQUIREMENTS}` - What it should do -- `{BASE_SHA}` - Starting commit -- `{HEAD_SHA}` - Ending commit -- `{DESCRIPTION}` - Brief summary +### 3. Triage and Act on Feedback +- **Critical:** Fix immediately — blocks all progress +- **Important:** Fix before proceeding to next task +- **Minor:** Note for later or fix if quick +- **Incorrect feedback:** Push back with technical reasoning and evidence -**3. Act on feedback:** -- Fix Critical issues immediately -- Fix Important issues before proceeding -- Note Minor issues for later -- Push back if reviewer is wrong (with reasoning) +**Validation:** All Critical and Important issues resolved before continuing ## Example ``` -[Just completed Task 2: Add verification function] - -You: Let me request code review before proceeding. - -BASE_SHA=$(git log --oneline | grep "Task 1" | head -1 | awk '{print $1}') -HEAD_SHA=$(git rev-parse HEAD) - -[Dispatch superpowers:code-reviewer subagent] - WHAT_WAS_IMPLEMENTED: Verification and repair functions for conversation index - PLAN_OR_REQUIREMENTS: Task 2 from docs/plans/deployment-plan.md - BASE_SHA: a7981ec - HEAD_SHA: 3df7661 - DESCRIPTION: Added verifyIndex() and repairIndex() with 4 issue types - -[Subagent returns]: - Strengths: Clean architecture, real tests - Issues: - Important: Missing progress indicators - Minor: Magic number (100) for reporting interval - Assessment: Ready to proceed - -You: [Fix progress indicators] -[Continue to Task 3] +[Completed Task 2: Add verification function] + +1. Capture SHAs: + BASE_SHA=a7981ec HEAD_SHA=3df7661 + +2. Dispatch code-reviewer subagent: + WHAT_WAS_IMPLEMENTED: Verification and repair functions for conversation index + PLAN_OR_REQUIREMENTS: Task 2 from docs/plans/deployment-plan.md + BASE_SHA: a7981ec + HEAD_SHA: 3df7661 + DESCRIPTION: Added verifyIndex() and repairIndex() with 4 issue types + +3. Reviewer returns: + Strengths: Clean architecture, real tests + Issues: + Important: Missing progress indicators + Minor: Magic number (100) for reporting interval + Assessment: Ready to proceed after Important fix + +4. Fix Important issue (progress indicators) → Continue to Task 3 ``` ## Integration with Workflows -**Subagent-Driven Development:** -- Review after EACH task -- Catch issues before they compound -- Fix before moving to next task - -**Executing Plans:** -- Review after each batch (3 tasks) -- Get feedback, apply, continue - -**Ad-Hoc Development:** -- Review before merge -- Review when stuck +| Workflow | Review Cadence | +|---|---| +| Subagent-Driven Development | After EACH task | +| Executing Plans | After each batch (3 tasks) | +| Ad-Hoc Development | Before merge or when stuck | ## Red Flags @@ -95,11 +88,11 @@ You: [Fix progress indicators] - Skip review because "it's simple" - Ignore Critical issues - Proceed with unfixed Important issues -- Argue with valid technical feedback +- Argue with valid technical feedback without evidence -**If reviewer wrong:** +**If reviewer is wrong:** - Push back with technical reasoning -- Show code/tests that prove it works -- Request clarification +- Show code/tests that prove correctness +- Request clarification on their concern -See template at: requesting-code-review/code-reviewer.md +See prompt templates at: `./code-reviewer.md` and `./reviewer-prompt.md` diff --git a/superpowers-antigravity/skills/subagent-driven-development/SKILL.md b/superpowers-antigravity/skills/subagent-driven-development/SKILL.md index a9a9454..d28c345 100644 --- a/superpowers-antigravity/skills/subagent-driven-development/SKILL.md +++ b/superpowers-antigravity/skills/subagent-driven-development/SKILL.md @@ -1,13 +1,13 @@ --- name: subagent-driven-development -description: Use when executing implementation plans with independent tasks in the current session +description: "Executes an implementation plan by dispatching a fresh subagent per task, running two-stage review (spec compliance then code quality) after each, and iterating until approved — managing the full cycle of implement → spec-review → quality-review → fix → re-review within one session. Use when executing implementation plans with independent tasks in the current session, dispatching subagents for plan execution, or running two-stage code review workflows." --- # Subagent-Driven Development -Execute plan by dispatching fresh subagent per task, with two-stage review after each: spec compliance review first, then code quality review. +Executes an implementation plan by dispatching a fresh subagent per task, with two-stage review after each: spec compliance first, then code quality. -**Core principle:** Fresh subagent per task + two-stage review (spec then quality) = high quality, fast iteration +**Core principle:** Fresh subagent per task + two-stage review (spec then quality) = high quality, fast iteration. ## When to Use @@ -29,6 +29,11 @@ digraph when_to_use { } ``` +- Have an implementation plan with independent tasks to execute +- Want same-session execution with fresh subagents (no context pollution) +- Need two-stage review (spec compliance + code quality) after each task +- For parallel-session execution with human review gates, use `superpowers:executing-plans` instead + **vs. Executing Plans (parallel session):** - Same session (no context switch) - Fresh subagent per task (no context pollution) @@ -84,9 +89,11 @@ digraph process { ## Prompt Templates -- `./implementer-prompt.md` - Dispatch implementer subagent -- `./spec-reviewer-prompt.md` - Dispatch spec compliance reviewer subagent -- `./code-quality-reviewer-prompt.md` - Dispatch code quality reviewer subagent +- `./implementer-prompt.md` — Dispatch implementer subagent +- `./spec-reviewer-prompt.md` — Dispatch spec compliance reviewer subagent +- `./code-quality-reviewer-prompt.md` — Dispatch code quality reviewer subagent + +**Validation:** All three templates must be filled before dispatching each task cycle. ## Example Workflow diff --git a/superpowers-antigravity/skills/systematic-debugging/SKILL.md b/superpowers-antigravity/skills/systematic-debugging/SKILL.md index 111d2a9..a8c0f54 100644 --- a/superpowers-antigravity/skills/systematic-debugging/SKILL.md +++ b/superpowers-antigravity/skills/systematic-debugging/SKILL.md @@ -1,13 +1,13 @@ --- name: systematic-debugging -description: Use when encountering any bug, test failure, or unexpected behavior, before proposing fixes +description: "Systematically diagnoses bugs through structured root cause analysis — reproducing issues, isolating variables, tracing execution paths, and verifying fixes. Use when encountering any bug, test failure, unexpected behavior, build error, or performance regression, especially when previous fix attempts have failed or the root cause is unclear." --- # Systematic Debugging ## Overview -Random fixes waste time and create new bugs. Quick patches mask underlying issues. +Finds root cause before attempting fixes. Random fixes waste time and create new bugs. **Core principle:** ALWAYS find root cause before attempting fixes. Symptom fixes are failure. @@ -23,19 +23,12 @@ If you haven't completed Phase 1, you cannot propose fixes. ## When to Use -Use for ANY technical issue: -- Test failures -- Bugs in production -- Unexpected behavior -- Performance problems -- Build failures -- Integration issues +Use for ANY technical issue: test failures, bugs in production, unexpected behavior, performance problems, build failures, integration issues. **Use this ESPECIALLY when:** - Under time pressure (emergencies make guessing tempting) - "Just one quick fix" seems obvious -- You've already tried multiple fixes -- Previous fix didn't work +- You've already tried multiple fixes or the previous fix didn't work - You don't fully understand the issue **Don't skip when:** @@ -45,172 +38,84 @@ Use for ANY technical issue: ## The Four Phases -You MUST complete each phase before proceeding to the next. +You MUST complete each phase before proceeding to the next. **Checkpoint:** confirm completion of each phase before advancing. ### Phase 1: Root Cause Investigation **BEFORE attempting ANY fix:** 1. **Read Error Messages Carefully** - - Don't skip past errors or warnings - - They often contain the exact solution - - Read stack traces completely - - Note line numbers, file paths, error codes + - Read stack traces completely — note line numbers, file paths, error codes + - They often contain the exact solution; don't skip past errors or warnings 2. **Reproduce Consistently** - - Can you trigger it reliably? - - What are the exact steps? - - Does it happen every time? - - If not reproducible → gather more data, don't guess + - Can you trigger it reliably with exact steps? + - If not reproducible, gather more data — don't guess 3. **Check Recent Changes** - - What changed that could cause this? - - Git diff, recent commits - - New dependencies, config changes - - Environmental differences + - `git diff`, recent commits, new dependencies, config changes, environmental differences 4. **Gather Evidence in Multi-Component Systems** **WHEN system has multiple components (CI → build → signing, API → service → database):** - **BEFORE proposing fixes, add diagnostic instrumentation:** + Add diagnostic instrumentation at each component boundary before proposing fixes: ``` For EACH component boundary: - - Log what data enters component - - Log what data exits component + - Log what data enters and exits - Verify environment/config propagation - Check state at each layer - - Run once to gather evidence showing WHERE it breaks - THEN analyze evidence to identify failing component - THEN investigate that specific component - ``` - - **Example (multi-layer system):** - ```bash - # Layer 1: Workflow - echo "=== Secrets available in workflow: ===" - echo "IDENTITY: ${IDENTITY:+SET}${IDENTITY:-UNSET}" - - # Layer 2: Build script - echo "=== Env vars in build script: ===" - env | grep IDENTITY || echo "IDENTITY not in environment" - - # Layer 3: Signing script - echo "=== Keychain state: ===" - security list-keychains - security find-identity -v - - # Layer 4: Actual signing - codesign --sign "$IDENTITY" --verbose=4 "$APP" + Run once → analyze evidence → identify failing component → investigate ``` - **This reveals:** Which layer fails (secrets → workflow ✓, workflow → build ✗) + See `defense-in-depth.md` in this directory for multi-layer validation patterns. 5. **Trace Data Flow** - **WHEN error is deep in call stack:** + **WHEN error is deep in call stack:** See `root-cause-tracing.md` in this directory for the complete backward tracing technique. - See `root-cause-tracing.md` in this directory for the complete backward tracing technique. + **Quick version:** Trace the bad value backward through the call stack — where does it originate? Fix at source, not at symptom. - **Quick version:** - - Where does bad value originate? - - What called this with bad value? - - Keep tracing up until you find the source - - Fix at source, not at symptom +**Phase 1 checkpoint:** Can you state the root cause in one sentence? If not, keep investigating. ### Phase 2: Pattern Analysis **Find the pattern before fixing:** -1. **Find Working Examples** - - Locate similar working code in same codebase - - What works that's similar to what's broken? - -2. **Compare Against References** - - If implementing pattern, read reference implementation COMPLETELY - - Don't skim - read every line - - Understand the pattern fully before applying - -3. **Identify Differences** - - What's different between working and broken? - - List every difference, however small - - Don't assume "that can't matter" +1. **Find Working Examples** — Locate similar working code in the same codebase +2. **Compare Against References** — Read reference implementations COMPLETELY, not skimmed +3. **Identify Differences** — List every difference between working and broken, however small +4. **Understand Dependencies** — Components, settings, config, environment, assumptions -4. **Understand Dependencies** - - What other components does this need? - - What settings, config, environment? - - What assumptions does it make? +**Phase 2 checkpoint:** Can you list the specific differences between working and broken code? ### Phase 3: Hypothesis and Testing -**Scientific method:** - -1. **Form Single Hypothesis** - - State clearly: "I think X is the root cause because Y" - - Write it down - - Be specific, not vague - -2. **Test Minimally** - - Make the SMALLEST possible change to test hypothesis - - One variable at a time - - Don't fix multiple things at once +**Scientific method — one variable at a time:** -3. **Verify Before Continuing** - - Did it work? Yes → Phase 4 - - Didn't work? Form NEW hypothesis - - DON'T add more fixes on top +1. **Form Single Hypothesis** — State clearly: "I think X is the root cause because Y" +2. **Test Minimally** — Make the SMALLEST possible change. One variable at a time. +3. **Verify** — Did it work? Yes → Phase 4. No → form NEW hypothesis. DON'T stack fixes. +4. **When You Don't Know** — Say so. Ask for help. Research more. Don't pretend. -4. **When You Don't Know** - - Say "I don't understand X" - - Don't pretend to know - - Ask for help - - Research more +**Phase 3 checkpoint:** Did your minimal change confirm or disprove the hypothesis? ### Phase 4: Implementation **Fix the root cause, not the symptom:** -1. **Create Failing Test Case** - - Simplest possible reproduction - - Automated test if possible - - One-off test script if no framework - - MUST have before fixing - - Use the `superpowers:test-driven-development` skill for writing proper failing tests - -2. **Implement Single Fix** - - Address the root cause identified - - ONE change at a time - - No "while I'm here" improvements - - No bundled refactoring - -3. **Verify Fix** - - Test passes now? - - No other tests broken? - - Issue actually resolved? - -4. **If Fix Doesn't Work** - - STOP - - Count: How many fixes have you tried? - - If < 3: Return to Phase 1, re-analyze with new information - - **If ≥ 3: STOP and question the architecture (step 5 below)** - - DON'T attempt Fix #4 without architectural discussion - +1. **Create Failing Test Case** — Simplest reproduction. Automated if possible. MUST exist before fixing. + - **REQUIRED SUB-SKILL:** Use superpowers:test-driven-development for writing proper failing tests +2. **Implement Single Fix** — Address root cause. ONE change. No "while I'm here" improvements. +3. **Verify Fix** — Test passes? No regressions? Issue actually resolved? +4. **If Fix Doesn't Work:** + - < 3 attempts: Return to Phase 1 with new information + - **>= 3 attempts: STOP — question the architecture (step 5)** 5. **If 3+ Fixes Failed: Question Architecture** + - Signs: each fix reveals new coupling, requires "massive refactoring", or creates new symptoms elsewhere + - **Discuss with your human partner before attempting more fixes** — this is a wrong architecture, not a failed hypothesis - **Pattern indicating architectural problem:** - - Each fix reveals new shared state/coupling/problem in different place - - Fixes require "massive refactoring" to implement - - Each fix creates new symptoms elsewhere - - **STOP and question fundamentals:** - - Is this pattern fundamentally sound? - - Are we "sticking with it through sheer inertia"? - - Should we refactor architecture vs. continue fixing symptoms? - - **Discuss with your human partner before attempting more fixes** - - This is NOT a failed hypothesis - this is a wrong architecture. +**Phase 4 checkpoint:** Does the fix pass the failing test without regressions? ## Red Flags - STOP and Follow Process @@ -231,16 +136,13 @@ If you catch yourself thinking: **If 3+ fixes failed:** Question the architecture (see Phase 4.5) -## your human partner's Signals You're Doing It Wrong - -**Watch for these redirections:** -- "Is that not happening?" - You assumed without verifying -- "Will it show us...?" - You should have added evidence gathering -- "Stop guessing" - You're proposing fixes without understanding -- "Ultrathink this" - Question fundamentals, not just symptoms -- "We're stuck?" (frustrated) - Your approach isn't working +## Human Partner Signals You're Doing It Wrong -**When you see these:** STOP. Return to Phase 1. +**Watch for these redirections — they mean STOP and return to Phase 1:** +- "Is that not happening?" — You assumed without verifying +- "Stop guessing" — Proposing fixes without understanding +- "Ultrathink this" — Question fundamentals, not symptoms +- "We're stuck?" (frustrated) — Your approach isn't working ## Common Rationalizations @@ -251,7 +153,6 @@ If you catch yourself thinking: | "Just try this first, then investigate" | First fix sets the pattern. Do it right from the start. | | "I'll write test after confirming fix works" | Untested fixes don't stick. Test first proves it. | | "Multiple fixes at once saves time" | Can't isolate what worked. Causes new bugs. | -| "Reference too long, I'll adapt the pattern" | Partial understanding guarantees bugs. Read it completely. | | "I see the problem, let me fix it" | Seeing symptoms ≠ understanding root cause. | | "One more fix attempt" (after 2+ failures) | 3+ failures = architectural problem. Question pattern, don't fix again. | @@ -266,31 +167,20 @@ If you catch yourself thinking: ## When Process Reveals "No Root Cause" -If systematic investigation reveals issue is truly environmental, timing-dependent, or external: - -1. You've completed the process -2. Document what you investigated -3. Implement appropriate handling (retry, timeout, error message) -4. Add monitoring/logging for future investigation +If systematic investigation reveals the issue is truly environmental, timing-dependent, or external: +1. Document what you investigated +2. Implement appropriate handling (retry, timeout, error message) +3. Add monitoring/logging for future investigation **But:** 95% of "no root cause" cases are incomplete investigation. ## Supporting Techniques -These techniques are part of systematic debugging and available in this directory: - -- **`root-cause-tracing.md`** - Trace bugs backward through call stack to find original trigger -- **`defense-in-depth.md`** - Add validation at multiple layers after finding root cause -- **`condition-based-waiting.md`** - Replace arbitrary timeouts with condition polling +Available in this directory: +- **`root-cause-tracing.md`** — Trace bugs backward through call stack to find original trigger +- **`defense-in-depth.md`** — Add validation at multiple layers after finding root cause +- **`condition-based-waiting.md`** — Replace arbitrary timeouts with condition polling **Related skills:** -- **superpowers:test-driven-development** - For creating failing test case (Phase 4, Step 1) -- **superpowers:verification-before-completion** - Verify fix worked before claiming success - -## Real-World Impact - -From debugging sessions: -- Systematic approach: 15-30 minutes to fix -- Random fixes approach: 2-3 hours of thrashing -- First-time fix rate: 95% vs 40% -- New bugs introduced: Near zero vs common +- **superpowers:test-driven-development** — For creating failing test case (Phase 4, Step 1) +- **superpowers:verification-before-completion** — Verify fix worked before claiming success diff --git a/superpowers-antigravity/skills/using-git-worktrees/SKILL.md b/superpowers-antigravity/skills/using-git-worktrees/SKILL.md index 51e87d9..8bc2e04 100644 --- a/superpowers-antigravity/skills/using-git-worktrees/SKILL.md +++ b/superpowers-antigravity/skills/using-git-worktrees/SKILL.md @@ -1,13 +1,13 @@ --- name: using-git-worktrees -description: Use when starting feature work that needs isolation from current workspace or before executing implementation plans - creates isolated git worktrees with smart directory selection and safety verification +description: "Use when starting feature work that needs isolation from the current workspace, before executing implementation plans, or when working on multiple branches simultaneously. Creates isolated git worktrees with smart directory selection and safety verification." --- # Using Git Worktrees ## Overview -Git worktrees create isolated workspaces sharing the same repository, allowing work on multiple branches simultaneously without switching. +Creates isolated workspaces sharing the same repository, enabling work on multiple branches simultaneously without switching. **Core principle:** Systematic directory selection + safety verification = reliable isolation. @@ -74,66 +74,32 @@ No .gitignore verification needed - outside project entirely. ## Creation Steps -### 1. Detect Project Name +### 1. Detect Project and Create Worktree ```bash project=$(basename "$(git rev-parse --show-toplevel)") -``` - -### 2. Create Worktree - -```bash -# Determine full path -case $LOCATION in - .worktrees|worktrees) - path="$LOCATION/$BRANCH_NAME" - ;; - ~/.config/superpowers/worktrees/*) - path="~/.config/superpowers/worktrees/$project/$BRANCH_NAME" - ;; -esac - -# Create worktree with new branch +# path determined by directory selection above git worktree add "$path" -b "$BRANCH_NAME" cd "$path" ``` -### 3. Run Project Setup - -Auto-detect and run appropriate setup: - -```bash -# Node.js -if [ -f package.json ]; then npm install; fi - -# Rust -if [ -f Cargo.toml ]; then cargo build; fi - -# Python -if [ -f requirements.txt ]; then pip install -r requirements.txt; fi -if [ -f pyproject.toml ]; then poetry install; fi - -# Go -if [ -f go.mod ]; then go mod download; fi -``` - -### 4. Verify Clean Baseline +**Checkpoint:** Does `git worktree list` show the new worktree? -Run tests to ensure worktree starts clean: +### 2. Run Project Setup (auto-detect) ```bash -# Examples - use project-appropriate command -npm test -cargo test -pytest -go test ./... +[ -f package.json ] && npm install +[ -f Cargo.toml ] && cargo build +[ -f requirements.txt ] && pip install -r requirements.txt +[ -f pyproject.toml ] && poetry install +[ -f go.mod ] && go mod download ``` -**If tests fail:** Report failures, ask whether to proceed or investigate. +### 3. Verify Clean Baseline -**If tests pass:** Report ready. +Run project-appropriate test command. **If tests fail:** report failures, ask whether to proceed. **If tests pass:** report ready. -### 5. Report Location +### 4. Report Location ``` Worktree ready at diff --git a/superpowers-antigravity/skills/writing-plans/SKILL.md b/superpowers-antigravity/skills/writing-plans/SKILL.md index 448ca31..a87b5bf 100644 --- a/superpowers-antigravity/skills/writing-plans/SKILL.md +++ b/superpowers-antigravity/skills/writing-plans/SKILL.md @@ -1,34 +1,33 @@ --- name: writing-plans -description: Use when you have a spec or requirements for a multi-step task, before touching code +description: "Use when you have a spec, requirements, or design for a multi-step implementation task and need to create a structured plan before touching code. Use when breaking down features into bite-sized TDD tasks with exact file paths, commands, and expected outputs." --- # Writing Plans ## Overview -Write comprehensive implementation plans assuming the engineer has zero context for our codebase and questionable taste. Document everything they need to know: which files to touch for each task, code, testing, docs they might need to check, how to test it. Give them the whole plan as bite-sized tasks. DRY. YAGNI. TDD. Frequent commits. +Creates comprehensive implementation plans with bite-sized TDD tasks. Assumes the implementing engineer has zero codebase context — documents exact file paths, complete code, test commands, and expected outputs for every step. -Assume they are a skilled developer, but know almost nothing about our toolset or problem domain. Assume they don't know good test design very well. +**Core principle:** Every step is one action (2-5 minutes). DRY. YAGNI. TDD. Frequent commits. **Announce at start:** "I'm using the writing-plans skill to create the implementation plan." -**Context:** This should be run in a dedicated worktree (created by brainstorming skill). +**Context:** Run in a dedicated worktree (created by brainstorming skill). **Save plans to:** `docs/plans/YYYY-MM-DD-.md` -## Bite-Sized Task Granularity +## Workflow -**Each step is one action (2-5 minutes):** -- "Write the failing test" - step -- "Run it to make sure it fails" - step -- "Implement the minimal code to make the test pass" - step -- "Run the tests and make sure they pass" - step -- "Commit" - step +### Step 1: Gather Requirements -## Plan Document Header +Collect spec, design docs, and acceptance criteria. Identify all components that need to change. -**Every plan MUST start with this header:** +**Checkpoint:** Can you state the goal in one sentence and list every component involved? + +### Step 2: Write the Plan Header + +Every plan MUST start with: ```markdown # [Feature Name] Implementation Plan @@ -36,15 +35,13 @@ Assume they are a skilled developer, but know almost nothing about our toolset o > **For Claude:** REQUIRED SUB-SKILL: Use superpowers:executing-plans to implement this plan task-by-task. **Goal:** [One sentence describing what this builds] - **Architecture:** [2-3 sentences about approach] - **Tech Stack:** [Key technologies/libraries] - ---- ``` -## Task Structure +### Step 3: Break Down into Tasks + +Each task follows this structure — every field is required: ```markdown ### Task N: [Component Name] @@ -55,62 +52,38 @@ Assume they are a skilled developer, but know almost nothing about our toolset o - Test: `tests/exact/path/to/test.py` **Step 1: Write the failing test** - -```python -def test_specific_behavior(): - result = function(input) - assert result == expected -``` +[Complete test code — not "add validation"] **Step 2: Run test to verify it fails** - Run: `pytest tests/path/test.py::test_name -v` Expected: FAIL with "function not defined" **Step 3: Write minimal implementation** - -```python -def function(input): - return expected -``` +[Complete implementation code] **Step 4: Run test to verify it passes** - Run: `pytest tests/path/test.py::test_name -v` Expected: PASS **Step 5: Commit** - -```bash -git add tests/path/test.py src/path/file.py -git commit -m "feat: add specific feature" -``` +`git add && git commit -m "feat: add specific feature"` ``` -## Remember -- Exact file paths always -- Complete code in plan (not "add validation") -- Exact commands with expected output -- Reference relevant skills with @ syntax -- DRY, YAGNI, TDD, frequent commits +**Checkpoint:** Does each task have exact file paths, complete code, exact commands, and expected output? -## Execution Handoff +### Step 4: Execution Handoff After saving the plan, offer execution choice: -**"Plan complete and saved to `docs/plans/.md`. Two execution options:** - -**1. Subagent-Driven (this session)** - I dispatch fresh subagent per task, review between tasks, fast iteration - -**2. Parallel Session (separate)** - Open new session with executing-plans, batch execution with checkpoints - -**Which approach?"** +| Option | Description | +|--------|-------------| +| **Subagent-Driven** (this session) | Dispatch fresh subagent per task, review between tasks. **REQUIRED SUB-SKILL:** superpowers:subagent-driven-development | +| **Parallel Session** (separate) | Open new session in worktree. **REQUIRED SUB-SKILL:** superpowers:executing-plans | -**If Subagent-Driven chosen:** -- **REQUIRED SUB-SKILL:** Use superpowers:subagent-driven-development -- Stay in this session -- Fresh subagent per task + code review +## Rules -**If Parallel Session chosen:** -- Guide them to open new session in worktree -- **REQUIRED SUB-SKILL:** New session uses superpowers:executing-plans +- **Exact file paths always** — never "the config file" +- **Complete code in plan** — never "add validation here" +- **Exact commands with expected output** — never "run the tests" +- **Reference relevant skills** with `superpowers:skill-name` syntax +- **One action per step** (2-5 minutes each) diff --git a/superpowers-antigravity/skills/writing-skills/SKILL.md b/superpowers-antigravity/skills/writing-skills/SKILL.md index 00b6a42..88f47e0 100644 --- a/superpowers-antigravity/skills/writing-skills/SKILL.md +++ b/superpowers-antigravity/skills/writing-skills/SKILL.md @@ -1,48 +1,35 @@ --- name: writing-skills -description: Use when creating new skills, editing existing skills, or verifying skills work before deployment +description: "Creates, validates, and tests SKILL.md files using TDD methodology and subagent verification. Use when creating new skills, editing existing SKILL.md files, testing skill effectiveness with subagents, or validating that skill instructions produce expected agent behavior." --- # Writing Skills ## Overview -**Writing skills IS Test-Driven Development applied to process documentation.** - -**Personal skills live in agent-specific directories (`~/.claude/skills` for Claude Code, `~/.codex/skills` for Codex)** - -You write test cases (pressure scenarios with subagents), watch them fail (baseline behavior), write the skill (documentation), watch tests pass (agents comply), and refactor (close loopholes). +Applies Test-Driven Development to process documentation. Write test cases (pressure scenarios with subagents), watch them fail (baseline behavior), write the skill, watch tests pass (agents comply), and refactor (close loopholes). **Core principle:** If you didn't watch an agent fail without the skill, you don't know if the skill teaches the right thing. -**REQUIRED BACKGROUND:** You MUST understand superpowers:test-driven-development before using this skill. That skill defines the fundamental RED-GREEN-REFACTOR cycle. This skill adapts TDD to documentation. - -**Official guidance:** For Anthropic's official skill authoring best practices, see anthropic-best-practices.md. This document provides additional patterns and guidelines that complement the TDD-focused approach in this skill. +**Personal skills live in:** `~/.claude/skills` (Claude Code), `~/.codex/skills` (Codex) -## What is a Skill? +**REQUIRED BACKGROUND:** You MUST understand superpowers:test-driven-development before using this skill. -A **skill** is a reference guide for proven techniques, patterns, or tools. Skills help future Claude instances find and apply effective approaches. +**Official guidance:** See `anthropic-best-practices.md` in this directory for Anthropic's official skill authoring best practices. -**Skills are:** Reusable techniques, patterns, tools, reference guides +## What is a Skill? -**Skills are NOT:** Narratives about how you solved a problem once +A **skill** is a reusable reference guide for proven techniques, patterns, or tools. **Skills are NOT** narratives about how you solved a problem once. ## TDD Mapping for Skills -| TDD Concept | Skill Creation | -| ----------------------- | ------------------------------------------------ | -| **Test case** | Pressure scenario with subagent | -| **Production code** | Skill document (SKILL.md) | -| **Test fails (RED)** | Agent violates rule without skill (baseline) | -| **Test passes (GREEN)** | Agent complies with skill present | -| **Refactor** | Close loopholes while maintaining compliance | -| **Write test first** | Run baseline scenario BEFORE writing skill | -| **Watch it fail** | Document exact rationalizations agent uses | -| **Minimal code** | Write skill addressing those specific violations | -| **Watch it pass** | Verify agent now complies | -| **Refactor cycle** | Find new rationalizations → plug → re-verify | - -The entire skill creation process follows RED-GREEN-REFACTOR. +| TDD Concept | Skill Creation | +|---|---| +| Test case | Pressure scenario with subagent | +| Production code | Skill document (SKILL.md) | +| RED (test fails) | Agent violates rule without skill (baseline) | +| GREEN (test passes) | Agent complies with skill present | +| Refactor | Close loopholes while maintaining compliance | ## When to Create a Skill @@ -71,7 +58,6 @@ API docs, syntax guides, tool documentation (office docs) ## Directory Structure - ``` skills/ skill-name/ @@ -79,61 +65,36 @@ skills/ supporting-file.* # Only if needed ``` -**Flat namespace** - all skills in one searchable namespace - -**Separate files for:** -1. **Heavy reference** (100+ lines) - API docs, comprehensive syntax -2. **Reusable tools** - Scripts, utilities, templates - -**Keep inline:** -- Principles and concepts -- Code patterns (< 50 lines) -- Everything else +**Flat namespace.** Separate files only for heavy reference (100+ lines) or reusable tools. Keep everything else inline. ## SKILL.md Structure -**Frontmatter (YAML):** -- Only two fields supported: `name` and `description` -- Max 1024 characters total -- `name`: Use letters, numbers, and hyphens only (no parentheses, special chars) -- `description`: Third-person, describes ONLY when to use (NOT what it does) - - Start with "Use when..." to focus on triggering conditions - - Include specific symptoms, situations, and contexts - - **NEVER summarize the skill's process or workflow** (see CSO section for why) - - Keep under 500 characters if possible +**Frontmatter (YAML):** Only `name` and `description` fields. Max 1024 characters total. +- `name`: Letters, numbers, hyphens only +- `description`: Quoted string. Third-person. Start with "Use when..." — triggering conditions only, NEVER workflow summary (see CSO section). Under 500 characters. ```markdown --- -name: Skill-Name-With-Hyphens -description: Use when [specific triggering conditions and symptoms] +name: skill-name-with-hyphens +description: "Use when [specific triggering conditions and symptoms]" --- # Skill Name ## Overview -What is this? Core principle in 1-2 sentences. +Core principle in 1-2 sentences. ## When to Use -[Small inline flowchart IF decision non-obvious] - -Bullet list with SYMPTOMS and use cases -When NOT to use +Bullet list with symptoms and use cases. When NOT to use. ## Core Pattern (for techniques/patterns) -Before/after code comparison +Before/after code comparison. ## Quick Reference -Table or bullets for scanning common operations - -## Implementation -Inline code for simple patterns -Link to file for heavy reference or reusable tools +Table or bullets for scanning. ## Common Mistakes -What goes wrong + fixes - -## Real-World Impact (optional) -Concrete results +What goes wrong + fixes. ``` diff --git a/wechat-operation/evidencing-wechat-tech-posts/SKILL.md b/wechat-operation/evidencing-wechat-tech-posts/SKILL.md index 43f32a1..6d61bda 100644 --- a/wechat-operation/evidencing-wechat-tech-posts/SKILL.md +++ b/wechat-operation/evidencing-wechat-tech-posts/SKILL.md @@ -1,22 +1,36 @@ --- name: evidencing-wechat-tech-posts -description: Produces credible case-study writeups, non-hallucinated data handling, and fact-check lists for WeChat tech posts. Use when the user needs a project recap, results narrative, citations guidance, or “what to verify” checklists in tech/engineering WeChat公众号. +description: “Produces credible case-study writeups, non-hallucinated data handling, and fact-check lists for WeChat tech posts. Use when the user needs a project recap, results narrative, citations guidance, data verification, or 'what to verify' checklists in tech/engineering WeChat公众号.” --- # Evidencing WeChat Tech Posts ## When to use -案例复盘写作、数据引用合规、事实核查清单、避免“张口就来”。 +案例复盘写作、数据引用合规、事实核查清单、避免”张口就来”。Use when drafting case studies, verifying data citations, building fact-check checklists, or writing project retrospectives. ## Inputs - 案例要素：背景/目标/约束/方案/结果/教训（缺省可用 {待补充}） - 是否允许使用外部来源（若无来源则只给核实路径） +## Workflow +1. **收集案例要素** — 确认背景/目标/约束/方案/结果/教训六要素齐全，缺失项标记 `{待补充}` +2. **构建复盘结构** — 按”问题→选择→取舍→验证→结果→反思”组织叙事 + - ✅ 检查点：每个环节有具体数据或事实支撑，无空泛描述 +3. **生成事实核查清单** — 列出所有需核实点、核实方法、核实状态 + - ✅ 检查点：清单 ≥8 条，每条含核实路径 +4. **生成可复用模板** — 输出读者可直接套用的复盘/核查模板（参见 TEMPLATES.md） +5. **终审质量关** — 逐条检查质量标准，确认无夸大表述 + ## Output expectations - 复盘结构：问题→选择→取舍→验证→结果→反思 - 读者可复用模板/检查清单（≥8条） - “事实核查清单”：列出所有需要核实点 + 核实方法 ## Quality checks -- 不夸大：禁用“颠覆/史诗级”这类词 +- 不夸大：禁用”颠覆/史诗级”这类词 - 结果表述要带边界：条件/口径/数据来源 +- 所有数据引用必须标注来源或标记”需核实” + +## Examples +User: “帮我写一个从 MySQL 迁移到 TiDB 的案例复盘” +Assistant: 按复盘六要素收集信息，输出完整复盘文章 + 8条事实核查清单 + 可复用迁移决策模板。 diff --git a/wechat-operation/formatting-wechat-tech-posts/SKILL.md b/wechat-operation/formatting-wechat-tech-posts/SKILL.md index 2ba5dd5..eb195ff 100644 --- a/wechat-operation/formatting-wechat-tech-posts/SKILL.md +++ b/wechat-operation/formatting-wechat-tech-posts/SKILL.md @@ -1,17 +1,25 @@ --- name: formatting-wechat-tech-posts -description: Designs image plans and rewrites formatting for WeChat-friendly readability (short paragraphs, bolding, separators, restrained emoji). Use when the user asks for illustration ideas, layout guidance, or to convert a draft into publish-ready WeChat formatting. +description: “Designs image plans and rewrites formatting for WeChat-friendly readability including short paragraphs, bolding, separators, and restrained emoji. Use when the user asks for illustration ideas, layout guidance, visual formatting, or to convert a draft into publish-ready WeChat formatting.” --- # Formatting WeChat Tech Posts ## When to use -配图脚本、排版优化、把“论文感”改成“公众号感”。 +配图脚本、排版优化、把”论文感”改成”公众号感”。Use when designing illustrations, optimizing layout, reformatting drafts for WeChat readability, or planning image placements. ## Inputs - 文章主题或全文草稿 - 风格（科技感/极简/活泼但克制） +## Workflow +1. **分析文章结构** — 识别核心段落、关键论点、适合配图的位置 +2. **设计配图方案** — 为每个关键位置规划图类型、信息点、图中文字 + - ✅ 检查点：6-8张配图建议齐全，图中文字均 ≤12字 +3. **排版重构** — 短段落化、关键句加粗、清单化、分隔线、emoji克制 + - ✅ 检查点：每段 ≤4行，每屏加粗 ≤2处 +4. **输出终稿** — 合并配图方案与排版版全文（参见 TEMPLATES.md 排版模板） + ## Output expectations - 6-8 张配图建议：位置、图类型、信息点、图中文字 - 排版版全文：短段落、关键句加粗、清单化、分隔线、emoji克制 @@ -20,3 +28,8 @@ description: Designs image plans and rewrites formatting for WeChat-friendly rea - 一屏不超过2处加粗 - 每段 ≤4 行（尽量） - 图中文字 ≤12字/条 +- emoji使用克制，每屏 ≤1个 + +## Examples +User: “这篇 Kubernetes 调度器的文章排版太学术了，帮我改成公众号风格” +Assistant: 输出配图方案（6张图含位置与文字）+ 排版重构版全文（短段落、加粗关键句、清单化）。 diff --git a/wechat-operation/ideating-wechat-tech-topics/SKILL.md b/wechat-operation/ideating-wechat-tech-topics/SKILL.md index bc1ef15..c96c143 100644 --- a/wechat-operation/ideating-wechat-tech-topics/SKILL.md +++ b/wechat-operation/ideating-wechat-tech-topics/SKILL.md @@ -1,29 +1,39 @@ --- name: ideating-wechat-tech-topics -description: Generates WeChat tech article topics, series, and angles with difficulty and “hit potential” scoring. Use when the user asks for topic ideas, content calendars, anti-myth angles, or serialized planning for tech/engineering WeChat公众号. +description: “Generates WeChat tech article topics, series blueprints, and angles with difficulty and hit-potential scoring. Use when the user asks for topic brainstorming, content calendars, anti-myth angles, series planning, or hit-potential evaluation for tech/engineering WeChat公众号.” --- # Ideating WeChat Tech Topics ## When to use -选题池、内容月历、系列策划、反常识选题、爆款潜质评估。 +选题池、内容月历、系列策划、反常识选题、爆款潜质评估。Use when brainstorming topics, building content calendars, planning article series, or evaluating hit potential for tech accounts. ## Inputs - 领域 {必填或推断} - 读者画像 {可选} - 内容形式偏好（教程/清单/测评/复盘/观点） +## Workflow +1. **按读者任务场景分桶** — 将选题分为上手/避坑/提效/决策四类 + - ✅ 检查点：每个桶至少5个选题 +2. **多角度拓展** — 给每桶做”强对比/强清单/强复盘”角度 +3. **评分与排序** — 给出收益、难度、潜质评分与原因（透明可复盘） + - ✅ 检查点：评分维度一致，原因具体可追溯 +4. **栏目化规划** — 提炼10个栏目名，每个含3期规划 +5. **反常识选题** — 输出10个”误区句→正确句→清单标题”组合 +6. **附提示词** — 生成可复制提示词（参见 TEMPLATES.md） + ## Output expectations - 30 个选题（含收益、难度、潜质评分、形式建议） - 10 个栏目名 + 每个 3 期规划 -- 10 个“反常识 + 可落地”选题（含误区句/正确句/清单标题） +- 10 个”反常识 + 可落地”选题（含误区句/正确句/清单标题） - 附可复制提示词（见 TEMPLATES.md） -## Workflow -1) 先按“读者任务场景”分桶（上手/避坑/提效/决策） -2) 再给每桶做“强对比/强清单/强复盘”角度 -3) 给出评分与原因（透明可复盘） - ## Quality checks - 标题雏形要具体（对象/场景/收益） -- 避免“宏大叙事”，优先“可交付物” +- 避免”宏大叙事”，优先”可交付物” +- 每个选题必须有明确的读者收益点 + +## Examples +User: “我做云原生方向，帮我出30个选题” +Assistant: 按上手/避坑/提效/决策分桶输出30个选题（含评分），10个栏目规划，10个反常识选题。 diff --git a/wechat-operation/iterating-wechat-tech-posts/SKILL.md b/wechat-operation/iterating-wechat-tech-posts/SKILL.md index 015b890..663ce27 100644 --- a/wechat-operation/iterating-wechat-tech-posts/SKILL.md +++ b/wechat-operation/iterating-wechat-tech-posts/SKILL.md @@ -1,18 +1,28 @@ --- name: iterating-wechat-tech-posts -description: Generates endings/CTAs, pre-publish editorial QA, sentence sharpening, and post-performance retrospectives for WeChat tech posts. Use when the user needs a strong ending, final edit pass, or analytics-driven iteration plan for tech/engineering WeChat公众号. +description: “Generates endings and CTAs, pre-publish editorial QA, sentence sharpening, and post-performance retrospectives for WeChat tech posts. Use when the user needs a strong ending, final edit pass, paragraph sharpening, analytics review, or iteration plan for tech/engineering WeChat公众号.” --- # Iterating WeChat Tech Posts ## When to use -结尾三版本、发布前质检、句子变锋利、数据复盘、下一篇怎么改。 +结尾三版本、发布前质检、句子变锋利、数据复盘、下一篇怎么改。Use when writing endings, running pre-publish QA, sharpening paragraphs, reviewing post analytics, or planning next iterations. ## Inputs - 文章主题/正文 - 发布数据（阅读量/完读率/分享/收藏/留言等）可选 - 目标偏好：涨粉/收藏/转发/留言 +## Workflow +1. **生成结尾方案** — 输出实用派/观点派/福利派三种结尾 + - ✅ 检查点：每种结尾克制自然，无硬推感 +2. **发布前质检** — 检查结构、收益、术语密度、例子贴近度、不确定事实 + - ✅ 检查点：所有不确定事实已列入核实清单 +3. **段落锐化** — 逐段改写提升信息密度，输出删除/替换清单 + - ✅ 检查点：改写不改变原意 +4. **数据复盘**（若有发布数据）— 原因推断、改进建议、后续3个选题 +5. **输出迭代计划** — 综合以上结果，给出下一篇改进方向（参见 TEMPLATES.md） + ## Output expectations - 3种结尾：实用派/观点派/福利派（克制自然） - 发布前质检：结构、收益、术语密度、例子贴近度、不确定事实清单 @@ -20,5 +30,10 @@ description: Generates endings/CTAs, pre-publish editorial QA, sentence sharpeni - 数据复盘：原因推断、下次改法、后续3个选题 ## Quality checks -- CTA 不要“营业员式硬推” +- CTA 不要”营业员式硬推” - 改写不改变原意，但提升信息密度与可读性 +- 复盘建议必须具体可执行，不可泛泛而谈 + +## Examples +User: “这篇文章阅读量2000但完读率只有15%，帮我分析下怎么改” +Assistant: 输出数据复盘（完读率低的3个可能原因）+ 段落锐化建议 + 后续3个选题方向。 diff --git a/wechat-operation/outlining-wechat-tech-posts/SKILL.md b/wechat-operation/outlining-wechat-tech-posts/SKILL.md index 0de33a8..f9b9026 100644 --- a/wechat-operation/outlining-wechat-tech-posts/SKILL.md +++ b/wechat-operation/outlining-wechat-tech-posts/SKILL.md @@ -1,12 +1,12 @@ --- name: outlining-wechat-tech-posts -description: Builds WeChat-friendly outlines for tech posts, including multi-level TOC, reader-benefit lines per section, pitfalls and action checklists, and 30-second skim summaries. Use when the user asks for outlines, structures, or tutorial-style blueprints for tech/engineering WeChat公众号. +description: “Builds WeChat-friendly outlines for tech posts including multi-level TOC, reader-benefit lines per section, pitfall checklists, action checklists, and 30-second skim summaries. Use when the user asks for outlines, article structures, tutorial blueprints, or content skeletons for tech/engineering WeChat公众号.” --- # Outlining WeChat Tech Posts ## When to use -大纲、目录、结构重建、教程型骨架（步骤+检查点+报错）。 +大纲、目录、结构重建、教程型骨架（步骤+检查点+报错）。Use when building outlines, restructuring articles, designing tutorial skeletons, or creating content blueprints. ## Inputs - 主题 @@ -14,12 +14,27 @@ description: Builds WeChat-friendly outlines for tech posts, including multi-lev - 长度目标（默认 1200-2000 字） - 读者水平（默认中级） +## Workflow +1. **确定内容类型与读者水平** — 明确教程/科普/深度解读等类型 +2. **构建3级标题大纲** — 按”先结论后细节”原则搭建结构 + - ✅ 检查点：每节有”读者收益句” +3. **填充落地支撑** — 每节至少包含例子/类比/步骤之一 + - ✅ 检查点：无空洞章节 +4. **添加必备模块** — 误区澄清、踩坑清单、行动清单、30秒速读版 +5. **教程型额外步骤** — 补充前置条件、检查点、常见失败原因、最终交付物 +6. **终审** — 检查结构完整性与长度目标匹配度（参见 TEMPLATES.md 大纲模板） + ## Output expectations - 3级标题大纲 -- 每节有“读者收益句” +- 每节有”读者收益句” - 必含：误区澄清、踩坑清单、行动清单、30秒速读版要点 - 教程型：前置条件、步骤1-7、检查点、常见失败原因、最终交付物 ## Quality checks - 先结论后细节 -- 每节都有“例子/类比/步骤”至少一个落地支撑 +- 每节都有”例子/类比/步骤”至少一个落地支撑 +- 大纲层级清晰，不超过3级 + +## Examples +User: “帮我列一个 Docker 多阶段构建的教程大纲” +Assistant: 输出3级标题大纲（含前置条件、7步骤、检查点、常见失败原因）+ 每节读者收益句 + 30秒速读版。 diff --git a/wechat-operation/planning-wechat-tech-account/SKILL.md b/wechat-operation/planning-wechat-tech-account/SKILL.md index db1c0a3..2aa6109 100644 --- a/wechat-operation/planning-wechat-tech-account/SKILL.md +++ b/wechat-operation/planning-wechat-tech-account/SKILL.md @@ -1,12 +1,12 @@ --- name: planning-wechat-tech-account -description: Defines WeChat tech public-account positioning, audience segmentation, content pillars, and long-term columns. Use when the user asks about account positioning, reader personas, content strategy, or column planning for a tech/engineering WeChat公众号. +description: “Defines WeChat tech public-account positioning, audience segmentation, content pillars, and long-term column planning. Use when the user asks about account positioning, reader personas, content strategy, column design, or editorial calendar planning for a tech/engineering WeChat公众号.” --- # Planning WeChat Tech Account ## When to use -Use this Skill when the user wants: 账号定位、读者画像、内容支柱、栏目化、长期选题规划。 +账号定位、读者画像、内容支柱、栏目化、长期选题规划。Use when defining account positioning, segmenting audiences, designing content pillars, planning columns, or building long-term editorial calendars. ## Inputs to collect (ask only if missing) - 领域/擅长点 @@ -15,6 +15,17 @@ Use this Skill when the user wants: 账号定位、读者画像、内容支柱 - 风格偏好（克制/犀利/幽默程度） If any are missing, assume reasonable defaults and clearly label placeholders like `{待补充}`. +## Workflow +1. **锁定定位** — 用一句话锁定”写给谁 + 解决什么 + 凭什么信” + - ✅ 检查点：定位句具体且可区分，不是泛科技大杂烩 +2. **拆解读者分层** — 拆3类读者（初级/中级/决策者），写清”场景/恐惧/确定性” + - ✅ 检查点：每层读者有明确差异化的痛点 +3. **生成内容支柱** — 3个内容支柱 + 每个5个选题 +4. **栏目规划** — 设计栏目名、固定骨架、10期规划 + - ✅ 检查点：栏目间差异明显（科普/实战/观点至少分开） +5. **风格与禁忌清单** — 输出可直接当写作规范的清单 +6. **输出提示词** — 生成可复用的定位/画像/栏目提示词（参见 TEMPLATES.md） + ## Output expectations - 一句话定位 - 读者分层（初级/中级/决策者） @@ -22,15 +33,9 @@ If any are missing, assume reasonable defaults and clearly label placeholders li - 栏目设计（栏目名、固定骨架、10 期规划） - 风格与禁忌清单（可直接当写作规范） -## Workflow -1) 用一句话锁定“写给谁 + 解决什么 + 凭什么信” -2) 拆 3 类读者，写清他们的“场景/恐惧/确定性” -3) 生成内容支柱并规划成系列栏目（让读者形成期待） -4) 输出可复用提示词（见 TEMPLATES.md） - ## Quality checks -- 每条建议都要“可执行”（能直接照做） -- 不要空泛口号；避免“泛科技大杂烩” +- 每条建议都要”可执行”（能直接照做） +- 不要空泛口号；避免”泛科技大杂烩” - 栏目之间差异要明显（科普/实战/观点至少分开） ## Examples diff --git a/wechat-operation/titling-wechat-tech-posts/SKILL.md b/wechat-operation/titling-wechat-tech-posts/SKILL.md index a9a871f..cc9529d 100644 --- a/wechat-operation/titling-wechat-tech-posts/SKILL.md +++ b/wechat-operation/titling-wechat-tech-posts/SKILL.md @@ -1,12 +1,12 @@ --- name: titling-wechat-tech-posts -description: Crafts and rewrites WeChat tech post titles across multiple patterns (list, contrast, outcome, scenario, anti-myth, template). Use when the user needs headline brainstorming or “restrained but clickable” title rewrites for tech/engineering WeChat公众号. +description: “Crafts and rewrites WeChat tech post titles across multiple patterns including list, contrast, outcome, scenario, anti-myth, and template styles. Use when the user needs headline brainstorming, title rewrites, clickability optimization, or restrained-but-effective titles for tech/engineering WeChat公众号.” --- # Titling WeChat Tech Posts ## When to use -需要标题池、标题结构化、标题克制改写、避免标题党但要高点击。 +需要标题池、标题结构化、标题克制改写、避免标题党但要高点击。Use when brainstorming headlines, rewriting titles, optimizing clickability, or generating title variations across styles. ## Inputs - 主题 @@ -14,11 +14,25 @@ description: Crafts and rewrites WeChat tech post titles across multiple pattern - 风格（爆款风/克制风/学术风） - 是否允许数字与对比（默认允许但不夸大） +## Workflow +1. **分析主题与读者** — 明确对象/场景/收益三要素 +2. **生成标题池** — 按6种结构（清单/对比/结果/场景/反常识/模板）各生成标题 + - ✅ 检查点：共 ≥20个标题，覆盖指定结构 +3. **标注元信息** — 每个标题标注适合读者层级 + 点击诱因点 +4. **克制改写**（若有原标题）— 输出10个”更克制但更想点”的改写版本 + - ✅ 检查点：无编造数据，无夸大表述 +5. **终审** — 逐条检查具体性（对象+场景+收益齐全）（参见 TEMPLATES.md） + ## Output expectations - 20 个标题，覆盖指定结构 - 每个标题标注：适合读者层级 + 点击诱因点 -- 10 个“更克制但更想点”的改写版本（若给了原标题） +- 10 个”更克制但更想点”的改写版本（若给了原标题） ## Quality checks -- 不编造数据；若没有真实数字，不写“提升30%”，改成“明显/显著/可观” +- 不编造数据；若没有真实数字，不写”提升30%”，改成”明显/显著/可观” - 标题必须更具体：对象 + 场景 + 收益 +- 避免标题党式夸张，保持技术公信力 + +## Examples +User: “帮我给这篇 Redis 缓存穿透的文章起20个标题” +Assistant: 输出20个标题（覆盖清单/对比/场景等6种结构），每个标注读者层级与点击诱因。 diff --git a/wechat-operation/writing-wechat-tech-posts/SKILL.md b/wechat-operation/writing-wechat-tech-posts/SKILL.md index 0f73a43..5e67b98 100644 --- a/wechat-operation/writing-wechat-tech-posts/SKILL.md +++ b/wechat-operation/writing-wechat-tech-posts/SKILL.md @@ -1,39 +1,51 @@ --- name: writing-wechat-tech-posts -description: Writes complete WeChat tech posts (hook, TOC, body, checklists, image placement, layout notes, summaries). Use when the user asks to draft a WeChat tech article, generate reusable prompts for writing, or turn a topic/outline into a publish-ready post. +description: “Writes complete publish-ready WeChat tech posts including hooks, TOC, body, checklists, image placement, layout notes, and summaries. Use when the user asks to draft a WeChat tech article, generate reusable writing prompts, popularize complex concepts, or turn a topic or outline into a publish-ready post.” --- # Writing WeChat Tech Posts ## When to use -一键成稿、开头钩子、分节写作、复杂概念科普化、教程/深度文输出、提示词库生成。 +一键成稿、开头钩子、分节写作、复杂概念科普化、教程/深度文输出、提示词库生成。Use when drafting full articles, writing hooks, popularizing complex concepts, generating writing prompts, or converting outlines to publish-ready posts. ## Inputs -- 账号定位/读者画像（缺省可用“工程/产品/研发从业者”） +- 账号定位/读者画像（缺省可用”工程/产品/研发从业者”） - 主题 - 内容类型 - 目标（学会/理解/能上手/能决策/能避坑） -- 合规：不编造数据、不确定要标注“需核实+核实路径” +- 合规：不编造数据、不确定要标注”需核实+核实路径” + +## Workflow +1. **收口需求** — 用”总控模板”确认主题、类型、读者、目标（参见 TEMPLATES.md） + - ✅ 检查点：所有输入字段已确认或标记默认值 +2. **撰写开头钩子** — 用”5种开头法”生成100-150字钩子 + - ✅ 检查点：钩子有明确的读者痛点或好奇心触发 +3. **构建文章结构** — 3级标题目录 + 每节”核心观点→解释→例子/类比→步骤/清单” +4. **正文写作** — 逐节撰写，术语密集处用”类比→定义→流程→误解→MVP”模式 + - ✅ 检查点：类比后必须有严谨定义，不确定事实已标注 +5. **补充清单与配图** — 至少1个踩坑清单 + 1个行动清单 + 配图建议 +6. **排版与结尾** — 加粗点/金句/分隔线/emoji克制 + 总结/互动/关注引导 +7. **生成摘要** — 30字摘要 + 80字摘要 + - ✅ 检查点：全文符合9项输出要求 ## Output expectations (publish-ready) 必须包含： 1) 3-5个备选标题（爆款风/克制风/学术风） 2) 开头钩子（100-150字） 3) 文章目录（3级标题） -4) 正文：每节“核心观点→解释→例子/类比→步骤/清单” +4) 正文：每节”核心观点→解释→例子/类比→步骤/清单” 5) 至少1个踩坑清单 + 1个行动清单 6) 配图建议（画什么/放哪段后） 7) 排版建议（加粗点/金句/分隔线/emoji克制） 8) 结尾：总结+互动提问+关注引导（自然克制） 9) 30字摘要 + 80字摘要 -## Workflow -1) 用“总控模板”收口需求并生成初稿（见 TEMPLATES.md） -2) 需要钩子时用“5种开头法” -3) 需要分节深写时用“观点-解释-例子-步骤”段落模板 -4) 遇到术语密集，改用“类比→定义→流程→误解→MVP” - ## Quality checks - 技术不降智：类比后必须给严谨定义 - 每屏信息密度适中：段落短、清单多 - 不确定事实必须显式标注与核实路径 +- 全文长度与内容类型匹配（教程型偏长，观点型偏短） + +## Examples +User: “帮我写一篇关于 gRPC vs REST 的科普文章” +Assistant: 输出完整发布稿：5个备选标题、开头钩子、3级目录、正文（含类比与严谨定义）、踩坑清单、行动清单、配图建议、排版建议、结尾、30字+80字摘要。