@namewta/speculo 0.1.0

package/speculo/skills/github-npm-ops/references/workflow-yaml-reference.md

@@ -0,0 +1,268 @@
+# release.yml 完整注解
+
+逐行解释 `.github/workflows/release.yml` 中每个选择的原因。
+
+## 完整示例
+
+```yaml
+name: Release
+
+on:
+  push:
+    tags:
+      - 'v*'
+
+jobs:
+  release:
+    runs-on: ubuntu-latest
+    name: Release to npm
+    permissions:
+      id-token: write
+      contents: write
+      packages: write
+    steps:
+      - name: Checkout
+        uses: actions/checkout@v4
+
+      - name: Setup environment
+        uses: ./.github/actions/setup
+        with:
+          registry-url: 'https://registry.npmjs.org'
+
+      - name: Verify tag matches package version
+        run: |
+          TAG="${{ github.ref }}"
+          TAG_VERSION="${TAG#refs/tags/v}"
+          PACKAGE_VERSION=$(node -e "console.log(require('./package.json').version)")
+          if [ "$TAG_VERSION" != "$PACKAGE_VERSION" ]; then
+            echo "Tag version ($TAG_VERSION) does not match package.json version ($PACKAGE_VERSION)"
+            exit 1
+          fi
+          echo "Version verified: v$PACKAGE_VERSION"
+
+      - name: Run lint
+        run: pnpm lint
+
+      - name: Run tests
+        run: pnpm test
+
+      - name: Build
+        run: pnpm build
+
+      - name: Verify bin entry
+        run: node scripts/verify-bin.mjs
+
+      - name: Extract release notes from CHANGELOGS.md
+        run: |
+          VERSION="${GITHUB_REF_NAME#v}"
+          awk -v v="$VERSION" '
+            $0 ~ "^## \\["v"\\]" { found=1; print; next }
+            found && /^## \[/ { exit }
+            found && /^---[[:space:]]*$/ { next }
+            found { print }
+          ' CHANGELOGS.md > release-notes.md
+
+          if [ ! -s release-notes.md ]; then
+            echo "::warning::CHANGELOGS.md 中未找到 [$VERSION] 段落，回退到自动生成。"
+            echo "See [CHANGELOGS.md](https://github.com/${{ github.repository }}/blob/main/CHANGELOGS.md) for details." > release-notes.md
+          fi
+
+      - name: Publish to npm
+        run: npm publish --provenance --access public
+        env:
+          NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+
+      - name: Create GitHub Release
+        uses: softprops/action-gh-release@v2
+        if: success()
+        with:
+          tag_name: ${{ github.ref_name }}
+          name: Release ${{ github.ref_name }}
+          body_path: release-notes.md
+          generate_release_notes: true
+          draft: false
+          prerelease: false
+        env:
+          GITHUB_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+## 逐项解释
+
+### 触发条件
+
+```yaml
+on:
+  push:
+    tags:
+      - 'v*'
+```
+
+- 只在 push 带 `v` 开头的 tag 时触发（如 `v0.0.2`、`v1.2.3-rc1`）
+- **不要**同时写 `branches`，否则每次 push main 都会触发 release
+- 如果想预发，用独立的 tag 模式（如 `v*-rc*`）区分
+
+### permissions
+
+```yaml
+permissions:
+  id-token: write
+  contents: write
+  packages: write
+```
+
+| 权限               | 作用                                                                                   |
+| ------------------ | -------------------------------------------------------------------------------------- |
+| `id-token: write`  | **必需**：用于 npm provenance（OIDC 签名）                                              |
+| `contents: write`  | **必需**：`softprops/action-gh-release` 创建 GitHub Release 需要                        |
+| `packages: write`  | 仅在同时发 GitHub Packages 时需要；纯 npm 发布可省略                                    |
+
+默认 `GITHUB_TOKEN` 只有 `contents: read`，这三项必须显式声明。
+
+### Checkout
+
+```yaml
+- uses: actions/checkout@v4
+```
+
+默认浅克隆（`fetch-depth: 1`）。如果发布说明需要完整历史（如 changelog 生成），加 `fetch-depth: 0`。
+
+### Setup environment
+
+```yaml
+- uses: ./.github/actions/setup
+  with:
+    registry-url: 'https://registry.npmjs.org'
+```
+
+复合 action，通常封装：
+
+```yaml
+- uses: actions/setup-node@v4
+  with:
+    node-version: '24.14.1'
+    registry-url: 'https://registry.npmjs.org'
+- uses: pnpm/action-setup@v2
+  with:
+    version: 9
+- run: pnpm install --frozen-lockfile
+```
+
+关键点：`registry-url` **必须**在 `setup-node` 里设置，它会生成 `.npmrc` 并让 `NODE_AUTH_TOKEN` 生效。
+
+### Verify tag matches package version
+
+防止错发：tag `v0.0.2` 指向一个 `package.json` 版本为 `0.0.1` 的 commit，会导致用户安装到错误版本。
+
+失败时 workflow 直接退出，不会执行任何发布动作。
+
+### Lint / Test / Build
+
+即使本地已经跑过，CI 再跑一遍保证：
+
+1. 发布的产物来自干净环境
+2. 锁文件（`pnpm-lock.yaml`）在 CI 下可复现
+3. Build 产物与 tag 对应的源码一致
+
+如果 repo 已有一个单独的 `ci.yml` 跑在 push/PR 上，这里仍保留是为了**再次校验 tag 指向的 commit**——tag 可能指向旧 commit。
+
+### Verify bin entry
+
+```yaml
+- run: node scripts/verify-bin.mjs
+```
+
+CLI 包专有：确认 `dist/cli/index.js` 存在、有 shebang、可执行。防止 tsconfig 出问题导致产物不完整。
+
+### Extract release notes from CHANGELOGS.md
+
+```yaml
+- name: Extract release notes from CHANGELOGS.md
+  run: |
+    VERSION="${GITHUB_REF_NAME#v}"
+    awk -v v="$VERSION" '
+      $0 ~ "^## \\["v"\\]" { found=1; print; next }
+      found && /^## \[/ { exit }
+      found && /^---[[:space:]]*$/ { next }
+      found { print }
+    ' CHANGELOGS.md > release-notes.md
+
+    if [ ! -s release-notes.md ]; then
+      echo "::warning::..." >&2
+      echo "See [CHANGELOGS.md](...) for details." > release-notes.md
+    fi
+```
+
+把 `## [X.Y.Z]` 段落抽到 `release-notes.md`，让下面的 `softprops/action-gh-release` 通过 `body_path` 注入到 GitHub Release 正文。
+
+**为什么必须有这一步**：仅用 `generate_release_notes: true` 时，GitHub 内部从 commit + PR + label 抽取 changelog；直 push main 流程没 PR，生成器只剩 `Full Changelog: vA...vB` 一行。CHANGELOG 是事实来源，注入它才能让 Release 正文非空。
+
+**awk 规则细节**与边界用例（包含 `[Unreleased]` 同时存在、版本号含连字符 / 多语言 CHANGELOG / `body_path` + `generate_release_notes` 共存语义）见 [release-notes-injection.md](release-notes-injection.md)。
+
+### Publish to npm
+
+```yaml
+- run: npm publish --provenance --access public
+  env:
+    NODE_AUTH_TOKEN: ${{ secrets.NPM_TOKEN }}
+```
+
+- `--provenance`：生成 sigstore 签名，要求 `id-token: write`
+- `--access public`：scoped 包首次发布必需；非 scoped 包加了也不会错
+- **位置在 GitHub Release 之前**：npm publish 不可回滚，如果后续步骤失败，至少 npm 发布是成功的
+
+### Create GitHub Release
+
+```yaml
+- uses: softprops/action-gh-release@v2
+  if: success()
+  with:
+    tag_name: ${{ github.ref_name }}
+    body_path: release-notes.md
+    generate_release_notes: true
+```
+
+- `if: success()`：只在 npm publish 成功后执行
+- `body_path: release-notes.md`：**正文头部**注入上一步抽取的 CHANGELOG 段落
+- `generate_release_notes: true`：**正文尾部**附 GitHub 自动生成的 What's Changed + Full Changelog compare 链接
+- 两者共存不冲突，效果是「人写的精炼说明 + 机器可追溯的索引」叠加
+- `softprops/action-gh-release@v2` 比废弃的 `actions/create-release@v1` 更稳定
+
+仅用 `generate_release_notes: true` 而不注入 `body_path`，在没有 PR 流量的仓库会得到几乎为空的 Release 正文，详见 [release-notes-injection.md](release-notes-injection.md) §1。
+
+## 常见变体
+
+### 使用 pnpm publish 代替 npm publish
+
+pnpm 也支持 `--access public --provenance`：
+
+```yaml
+- run: pnpm publish --provenance --access public --no-git-checks
+```
+
+`--no-git-checks` 避免 pnpm 检查当前 branch/tag（CI 中 detached HEAD 会被拒）。
+
+### 发布到 GitHub Packages（可选）
+
+```yaml
+- name: Publish to GitHub Packages
+  run: npm publish --registry=https://npm.pkg.github.com
+  env:
+    NODE_AUTH_TOKEN: ${{ secrets.GITHUB_TOKEN }}
+```
+
+需要单独的 setup step 指向 GitHub Packages，且 package 名必须是 `@owner/name` 形式。
+
+### Dry run（在 PR 里预演）
+
+```yaml
+- run: npm publish --dry-run --access public
+```
+
+放在一个仅 PR 触发的 workflow 里，帮你在合并前发现 tarball 问题。
+
+## 不推荐的做法
+
+- 在同一个 job 里既跑 push-to-main CI 又跑 release — 混乱，难以调试
+- 使用 `actions/create-release@v1` — 已废弃，推荐 `softprops/action-gh-release`
+- 用 `secrets.NPM_TOKEN` 直接传给 `npm publish` 命令行 — 会在日志里泄露
+- 跳过 `prepublishOnly` 或 CI 测试 — 已知会发布过坏包

package/speculo/skills/grill-me/SKILL.md

@@ -0,0 +1,40 @@
+---
+id: grill-me
+type: skill
+name: Grill Me
+description: 对计划、设计或决策进行逐问式压力测试；当用户要求 grill me、拷问方案、压力测试计划，或调用 command/grill-me 时使用。
+---
+
+# Grill Me
+
+## 何时使用
+
+当用户想压力测试计划、设计、架构选择、实现策略或决策树，并希望逐步达成共识时使用。
+
+如果问题可以通过探索代码库回答，先探索代码库，不把可查事实推回给用户。
+
+## 输入
+
+- 待拷问的计划、设计、架构选择或实现策略
+- 用户已表达的约束、偏好、风险承受度和成功标准
+- 可通过仓库探索确认的事实
+
+## 输出
+
+- 每轮一个问题
+- 每个问题附带推荐答案
+- 已锁定决策、剩余开放点和依赖关系的简短摘要
+- 需要持久化时，由调用方 command 或 workflow 归档摘要
+
+## 执行步骤
+
+1. 识别当前最影响方案正确性的未决问题。
+2. 如果答案能通过本地代码、文档或配置确认，先读取相关材料。
+3. 每次只问一个问题，避免问题组。
+4. 对每个问题给出推荐答案，并说明推荐理由。
+5. 用户回答后更新已锁定决策和剩余分支。
+6. 继续遍历决策树，直到核心分支达成共识或用户停止。
+
+## 渐进披露
+
+无额外文件。该 skill 的完整执行规则在本入口中。

package/speculo/skills/handoff/SKILL.md

@@ -0,0 +1,41 @@
+---
+id: handoff
+type: skill
+name: Handoff
+description: 将当前对话压缩成交接文档；当用户需要另一个 agent、另一个会话或 command/handoff 接手继续工作时使用。
+---
+
+# Handoff
+
+## 何时使用
+
+当当前上下文需要交给另一个 agent、另一个会话或异步执行者继续时使用。
+
+如果用户提供参数，把参数视为下一次会话的重点，并据此调整交接文档的内容取舍。
+
+## 输入
+
+- 当前对话目标、已完成工作和未完成事项
+- 已修改或需要关注的文件路径、命令、测试结果和阻塞点
+- 用户提供的下一次会话重点
+- 可推荐给下一个 agent 的 skill 名称
+
+## 输出
+
+- 保存到用户操作系统临时目录的脱敏交接文档
+- 文档路径
+- 推荐技能清单
+- 如调用方需要持久化，由调用方只归档文档路径和简短摘要
+
+## 执行步骤
+
+1. 收集当前目标、背景、已做工作、关键文件、验证结果、剩余风险和下一步。
+2. 删除 API key、密码、token、个人身份信息和其他敏感内容。
+3. 不复制 PRD、计划、ADR、issue、commit、diff 或其他已有产物正文；改用路径、URL 或 commit 引用。
+4. 添加 `推荐技能` 部分，列出下一个 agent 应优先读取或调用的技能。
+5. 将交接文档保存到用户操作系统临时目录，不保存到当前工作区。
+6. 返回文档路径和极简摘要。
+
+## 渐进披露
+
+无额外文件。该 skill 的完整执行规则在本入口中。

package/speculo/skills/scaffold-exercises/SKILL.md

@@ -0,0 +1,41 @@
+---
+id: scaffold-exercises
+type: skill
+name: Scaffold Exercises
+description: 创建课程章节与练习目录骨架并验证 lint；当用户要求 scaffold exercises、创建练习桩、设置课程章节，或调用 command/scaffold-exercises 时使用。
+---
+
+# Scaffold Exercises
+
+## 何时使用
+
+当项目包含课程练习结构，用户要求创建章节、练习、`problem/`、`solution/` 或 `explainer/` 桩时使用。
+
+## 输入
+
+- 章节和练习计划、编号、名称和变体类型
+- 项目中的练习根目录，默认 `exercises/`
+- 项目的 lint 命令，默认 `pnpm ai-hero-cli internal lint`
+- git 操作要求，例如是否需要 `git mv`、是否需要提交
+
+## 输出
+
+- 创建或移动的练习目录清单
+- 每个练习变体的 `readme.md` 桩
+- lint 运行结果和修复摘要
+- 如用户或调用方要求提交，输出 commit hash 或无法提交原因
+
+## 执行步骤
+
+1. 读取 `references/exercise-structure.md`，确认章节、练习、变体和必需文件规则。
+2. 从计划中提取章节名、练习名、编号和变体；缺失变体时默认使用 `explainer/`。
+3. 创建目录前列出影响路径；涉及重命名时使用 `git mv`。
+4. 为每个变体创建最小但非空的 `readme.md`。
+5. 运行 lint；按 `references/lint-and-git.md` 迭代修复，直到通过或记录阻塞。
+6. 仅在用户或调用方明确要求时提交 git。
+7. 不直接写 `.speculo/` 或 `.status.json`；需要归档时由调用方 command 或 workflow 负责。
+
+## 渐进披露
+
+- `references/exercise-structure.md`：解析章节、练习编号、变体目录和必需文件时读取。
+- `references/lint-and-git.md`：运行 lint、修复练习结构错误、移动目录或提交时读取。

package/speculo/skills/scaffold-exercises/references/exercise-structure.md

@@ -0,0 +1,85 @@
+# Exercise Structure
+
+## 目录命名
+
+章节目录位于 `exercises/` 下，格式：
+
+```text
+XX-section-name/
+```
+
+示例：
+
+```text
+01-retrieval-skill-building/
+```
+
+练习目录位于章节目录下，格式：
+
+```text
+XX.YY-exercise-name/
+```
+
+示例：
+
+```text
+01.03-retrieval-with-bm25/
+```
+
+规则：
+
+- 章节编号 = `XX`
+- 练习编号 = `XX.YY`
+- 名称使用 dash-case，小写字母和连字符
+- 练习编号必须匹配所属章节编号
+
+## 练习变体
+
+每个练习至少需要以下一个子文件夹：
+
+- `problem/`：带 TODO 的学生工作区
+- `solution/`：参考实现
+- `explainer/`：概念材料，不含 TODO
+
+创建桩时，除非计划另有说明，默认使用 `explainer/`。
+
+## 必需文件
+
+每个变体文件夹都需要一个 `readme.md`。
+
+`readme.md` 必须：
+
+- 非空
+- 包含真实内容，即使只有标题和一句描述
+- 没有失效链接
+
+最小桩：
+
+```md
+# Exercise Title
+
+这里写描述。
+```
+
+如果子文件夹包含代码，还需要一个超过 1 行的 `main.ts`。只有 `readme.md` 的练习桩可以是 readme-only。
+
+## 示例
+
+计划：
+
+```text
+Section 05: Memory Skill Building
+- 05.01 Introduction to Memory
+- 05.02 Short-term Memory (explainer + problem + solution)
+- 05.03 Long-term Memory
+```
+
+创建：
+
+```text
+exercises/05-memory-skill-building/05.01-introduction-to-memory/explainer/readme.md
+exercises/05-memory-skill-building/05.02-short-term-memory/explainer/readme.md
+exercises/05-memory-skill-building/05.02-short-term-memory/problem/readme.md
+exercises/05-memory-skill-building/05.02-short-term-memory/solution/readme.md
+exercises/05-memory-skill-building/05.03-long-term-memory/explainer/readme.md
+```

package/speculo/skills/scaffold-exercises/references/lint-and-git.md

@@ -0,0 +1,54 @@
+# Lint And Git
+
+## Lint 命令
+
+默认验证命令：
+
+```bash
+pnpm ai-hero-cli internal lint
+```
+
+如果项目文档或用户指定了其他命令，使用项目命令。
+
+## Lint 规则摘要
+
+linter 通常会检查：
+
+- 每个练习都有子文件夹，例如 `problem/`、`solution/`、`explainer/`
+- 至少存在 `problem/`、`explainer/` 或 `explainer.1/` 之一
+- 主子文件夹中存在非空 `readme.md`
+- 没有 `.gitkeep`
+- 没有 `speaker-notes.md`
+- `readme.md` 中没有失效链接
+- `readme.md` 中没有 `pnpm run exercise`
+- 每个含代码的子文件夹都有超过 1 行的 `main.ts`
+
+## 修复流程
+
+1. 运行 lint。
+2. 根据错误补齐目录、`readme.md` 或需要的 `main.ts`。
+3. 删除不允许的 `.gitkeep` 或 `speaker-notes.md`，但只删除本次创建或用户明确要求处理的文件。
+4. 修复失效链接或记录需要用户确认的链接变更。
+5. 重跑 lint，直到通过或出现外部阻塞。
+
+## 移动或重命名练习
+
+重新编号或移动练习时使用 `git mv`，保留 git 历史。
+
+示例：
+
+```bash
+git mv exercises/01-retrieval/01.03-embeddings exercises/01-retrieval/01.04-embeddings
+```
+
+移动后更新数字前缀并重新运行 lint。
+
+## 提交
+
+只有用户或调用方明确要求提交时才运行 `git commit`。
+
+提交前检查：
+
+- `git status --short`
+- 只包含本次练习脚手架相关改动，或提交命令明确指定路径
+- lint 已通过，或 commit message/交付说明中写明未通过原因

package/speculo/skills/speculo-write/SKILL.md

@@ -0,0 +1,53 @@
+---
+id: speculo-write
+type: skill
+name: Speculo Write
+description: 创建或改造 Speculo workflows、skills、commands 的原子能力；当用户要求根据参考项目、外部技能、当前规范或产品意图，设计、迁移、融合、更新 Speculo 资产时使用。
+---
+
+# Speculo Write
+
+## 何时使用
+
+当任务是新增、迁移、融合或改造 Speculo 的 `workflows/`、`skills/`、`commands/`、配套模板、引用资料或 `.speculo/` 状态骨架时使用。
+
+典型触发：
+
+- “把这个外部 skill 迁移进 Speculo”
+- “给 dev 加一个 review workflow”
+- “做一个一次性归档 command”
+- “把这几个旧技能融合成一个原子 skill”
+
+## 输入
+
+- 用户目标、成功标准、目标受众、约束和参考项目路径
+- 现有同类资产：`speculo/workflows/<cat>/`、`speculo/skills/`、`speculo/commands/`
+- 外部源材料：旧技能、参考 workflow、临时目录、README 索引、脚本、模板
+
+本 skill 自带全部 Speculo 规范，已内化到下方 `references/`，**编写时不外读仓库 `docs/`**。
+
+## 输出
+
+- 合规的 Speculo workflow、skill 或 command 资产
+- 必要的 `references/`、workflow phase 文件、workflow `_templates/` 或 command 内联模板
+- 必要的 `.speculo/` 初始骨架或状态索引更新建议
+- 文档、测试和残留路径检查清单
+
+## 执行步骤
+
+1. **判定资产类型** —— workflow、skill、command，或组合。规则见 `references/asset-selection-sop.md`。
+2. **读取同类资产** —— 看目标目录里现有资产的真实写法，对齐风格，不直接套用外部技能格式。
+3. **提取可复用行为** —— 从参考材料保留核心内容（触发、输入输出、铁律、边界、失败恢复、模板），只规范化路径、frontmatter、产物和渐进披露。
+4. **设计文件结构** —— 入口、别名、状态字段、产物路径和验证清单。
+5. **实施** —— 实施前确认不会覆盖用户已有改动；实施后同步索引、文档和测试。
+6. **验证** —— 旧路径和旧工具名没有回流，运行项目测试或记录无法运行原因；提交前过一遍 `references/validation-checklist.md`。
+
+## 渐进披露
+
+- `references/asset-selection-sop.md`：判断应做 workflow、skill 还是 command 时读取。
+- `references/workflow-authoring-sop.md`：创建或改造 workflow、phase、template、索引和状态字段时读取。
+- `references/skill-authoring-sop.md`：创建原子 skill、迁移外部技能、拆分 references 时读取。
+- `references/command-authoring-sop.md`：创建单步 command、调用 skill、设计归档产物时读取。
+- `references/persistence-contract-sop.md`：需要 `.status.json` schema、目录命名、frontmatter 最小集或写入责任时读取。
+- `references/migration-sop.md`：从 `temp/skills`、参考项目或旧 workflow 迁移能力时读取。
+- `references/validation-checklist.md`：提交前检查 frontmatter、路径、模板、`.speculo/`、测试和旧路径残留时读取。

package/speculo/skills/speculo-write/references/asset-selection-sop.md

@@ -0,0 +1,65 @@
+# Asset Selection SOP
+
+## 目标
+
+把用户的“做一个能力”翻译成 Speculo 的正确资产形态：workflow、skill、command，或它们的组合。
+
+## 判定规则
+
+### 做 Workflow
+
+选择 workflow，当能力满足任一条件：
+
+- 多阶段交付，需要 phase 文件、产物模板和 `.status.json`
+- 产物属于一次 change，需要写 `.speculo/<cat>/<change>/`
+- 会跨多轮对话推进，或需要 `current_phase`、`phase_history`
+- 是业务流程、开发流程、文档流程或运维流程
+
+分类：
+
+- `dev`：开发、PRD、TDD、review、docs-sync、诊断、issue 分解
+- `doc`：文章、素材、文档写作、编辑、塑形
+- `ops`：运维、发布、巡检、外部系统操作的多阶段流程
+
+### 做 Skill
+
+选择 skill，当能力满足任一条件：
+
+- 是 command 或 workflow 可复用的原子能力
+- 复制到其他项目仍能工作
+- 需要 `references/` 渐进披露
+- 不拥有持久化责任，不直接写 `.speculo/` 或 `.status.json`
+- 是工具集成、领域知识、决策 SOP 或可复用操作手册
+
+### 做 Command
+
+选择 command，当能力满足全部条件：
+
+- 单步动作或短流程
+- 不需要 phase 状态机
+- 产物只归档到 `.speculo/commands/<YYYY-MM-DD>-<cmd>-<topic>/`
+- 可以调用 skill，但不需要 workflow 的 change 生命周期
+
+### 做组合
+
+- command 触发 skill：例如一次性报告、归档、状态聚合
+- workflow 内嵌 skill：例如发布 workflow 调用 GitHub/npm 原子能力
+- workflow 融合旧 skill：当旧 skill 只服务某个 workflow，不再作为根 skill 分发
+
+## 反例
+
+- 不要把多阶段、有状态的流程塞进 skill。
+- 不要让 skill 直接写 `.speculo/`。
+- 不要为一次性命令创建 workflow。
+- 不要把 workflow-only 方法保留为根 skill，除非会被多个入口复用。
+
+## 输出决策
+
+在实施前写清：
+
+- 资产类型
+- 目标路径
+- 入口 id / alias
+- 持久化路径
+- 是否需要模板、references、scripts
+- 需要同步的索引、文档和测试