diff --git a/CATALOG.zh-CN.md b/CATALOG.zh-CN.md index 3d32e80..9cdc37c 100644 --- a/CATALOG.zh-CN.md +++ b/CATALOG.zh-CN.md @@ -10,11 +10,11 @@ | --- | --- | | 集合 | Personal Skills Collection | | 包数量 | 5 个第一方 Skill | -| 当前状态 | v0.1.1 已发布;独立 `review-loop agent-skill` acceptance 仍为 BLOCKED | +| 当前状态 | v0.1.1 已发布且可安装;独立 `review-loop agent-skill` 证据仍为 `BLOCKED` | | 稳定版本 | [v0.1.1](https://github.com/LightDevCoder/skills/releases/tag/v0.1.1) | | 安装权威 | [docs/INSTALLATION.zh-CN.md](docs/INSTALLATION.zh-CN.md) | | 发现检查 | [collection-discovery-tests.ps1](tests/collection-discovery-tests.ps1) | -| 证据 | [v0.1.1 release evidence](docs/evidence/releases/v0.1.1/) | +| 证据 | [v0.1.1 发布证据](docs/evidence/releases/v0.1.1/RELEASE_RECEIPT.zh-CN.md) | ## 已准入 Skill @@ -30,7 +30,7 @@ ### project-init - **作用:** 从最小 preset 初始化项目,保留既有指令并验证结果路径。 -- **调用:** User-invoked only。 +- **调用:** 仅 user-invoked。 - **包:** [skills/project-init/](skills/project-init/) - **状态:** 第一方已准入。 - **证据:** [package tests](skills/project-init/tests/);[使用指南](docs/zh-CN/skills/project-init.md)。 @@ -39,7 +39,7 @@ ### ask-light - **作用:** 从当前上下文推荐一个下一 Skill 或一个 bounded workflow recipe。 -- **调用:** User-invoked only;永不执行推荐结果。 +- **调用:** 仅 user-invoked;永不执行推荐结果。 - **包:** [skills/ask-light/](skills/ask-light/) - **状态:** 第一方已准入;支持显式 `next` 和 `workflow` 模式。 - **证据:** [scanner tests](skills/ask-light/tests/);[使用指南](docs/zh-CN/skills/ask-light.md)。 @@ -48,7 +48,7 @@ ### learn-anything - **作用:** 将证据充分的对话、笔记、workflow 或资料转成可复用 Agent Skill 方法。 -- **调用:** User-invoked only。 +- **调用:** 仅 user-invoked。 - **包:** [skills/learn-anything/](skills/learn-anything/) - **状态:** 第一方已准入;保留 source-sufficiency 与 deterministic package-build 边界。 - **证据:** [package contract](skills/learn-anything/SKILL.md);[使用指南](docs/zh-CN/skills/learn-anything.md)。 diff --git a/CHANGELOG.md b/CHANGELOG.md index 1c3ac9f..c2dccf4 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -38,8 +38,11 @@ drafted. [INSTALLATION_VERIFICATION.md](docs/evidence/releases/v0.1.1/INSTALLATION_VERIFICATION.md). - Structural and package evidence: [TEST_SUMMARY.md](docs/evidence/releases/v0.1.1/TEST_SUMMARY.md). -- Independent `review-loop agent-skill` acceptance remains `BLOCKED`; see - [release receipt](docs/evidence/releases/v0.1.1/RELEASE_RECEIPT.md). +- The five-package collection remains installable and its collection-quality + checks passed. Independent evaluator evidence for the `review-loop + agent-skill` acceptance gate remains `BLOCKED`; this does not block ordinary + installation or use. See the [release receipt](docs/evidence/releases/v0.1.1/RELEASE_RECEIPT.md) + for the exact evidence boundary. ## 0.1.0 — 2026-07-23 diff --git a/CHANGELOG.zh-CN.md b/CHANGELOG.zh-CN.md index 5aec210..55e1674 100644 --- a/CHANGELOG.zh-CN.md +++ b/CHANGELOG.zh-CN.md @@ -24,9 +24,11 @@ - 合并后的 release commit 上 GitHub Actions `collection-quality`:`PASS`。 - 整仓和单 Skill fresh install:使用 CLI `1.5.20`,均为 `PASS`。 - GitHub release:https://github.com/LightDevCoder/skills/releases/tag/v0.1.1 -- 整仓与单 Skill fresh-install 目标记录:[INSTALLATION_VERIFICATION.md](docs/evidence/releases/v0.1.1/INSTALLATION_VERIFICATION.md)。 -- 结构与包测试证据:[TEST_SUMMARY.md](docs/evidence/releases/v0.1.1/TEST_SUMMARY.md)。 -- 独立 `review-loop agent-skill` acceptance 仍为 `BLOCKED`;见[发布收据](docs/evidence/releases/v0.1.1/RELEASE_RECEIPT.md)。 +- 整仓与单 Skill fresh-install 目标记录:[INSTALLATION_VERIFICATION.zh-CN.md](docs/evidence/releases/v0.1.1/INSTALLATION_VERIFICATION.zh-CN.md)。 +- 结构与包测试证据:[TEST_SUMMARY.zh-CN.md](docs/evidence/releases/v0.1.1/TEST_SUMMARY.zh-CN.md)。 +- 五个包组成的集合仍可安装,`collection-quality` 检查已通过。`review-loop + agent-skill` acceptance gate 的独立 evaluator 证据仍为 `BLOCKED`;这不影响 + 一般安装或使用。准确证据边界见[发布收据](docs/evidence/releases/v0.1.1/RELEASE_RECEIPT.zh-CN.md)。 ## 0.1.0 — 2026-07-23 diff --git a/README.md b/README.md index 6bdfb25..e357a7e 100644 --- a/README.md +++ b/README.md @@ -14,8 +14,13 @@ invocation boundary, and small enough to inspect before use. > is published from commit `c50f1ef`. The release record and fresh-install evidence > live in [docs/evidence/releases/v0.1.1/](docs/evidence/releases/v0.1.1/). > -> Independent `review-loop agent-skill` acceptance remains `BLOCKED`; see the -> receipt for the exact boundary. +> **Release status:** The collection is published and usable. Installation and +> `collection-quality` checks passed for all five first-party Skills. The +> remaining release-acceptance limitation is the independent evaluator evidence +> for the `review-loop agent-skill` gate: that evidence is `BLOCKED` because a +> fresh independent evaluator record is not attached. This does not block +> installation or ordinary use; see the [release receipt](docs/evidence/releases/v0.1.1/RELEASE_RECEIPT.md) +> and [limitations](docs/evidence/releases/v0.1.1/LIMITATIONS.md) for the detailed boundary. ## Quick Start @@ -57,6 +62,31 @@ result. Read [Quick Start](examples/quick-start/README.md), the [Skill user guides](docs/skills/), and [workflow recipes](docs/workflows/) for inputs, outputs, handoffs, and stopping boundaries. +## External capabilities + +The five packages above are the core collection: installing this repository +provides all five first-party Skills listed in the catalog. + +Optional workflow capabilities are external or third-party dependencies and are +not included by default: + +- `grill-me` / `grilling` — `grill-me` is the user-facing entry point for a + one-session clarification interview; it starts the underlying model-invoked + `grilling` capability. Treat them as one capability, not two workflow steps. +- `research` — investigate an external fact or practice when a local preset is + insufficient. +- `to-spec` — turn an approved goal and constraints into a traceable + specification. +- `to-tickets` — turn an approved specification into dependency-ordered + tickets. +- `implement` — carry out one bounded, unblocked implementation ticket. +- `code-review` — provide specialist findings for a fixed change. +- `handoff` — preserve an accepted result or blocker for closeout or resumption. + +These capabilities may come from `mattpocock/skills` or another external +source. This repository does not copy them or install them automatically; +check their availability before selecting a workflow that names them. + ## First-party catalog | Skill | Purpose | Invocation | Package | diff --git a/README.zh-CN.md b/README.zh-CN.md index f611c6a..d6823de 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -6,13 +6,18 @@ `LightDevCoder/skills` 是公开的第一方 Agent Skills 集合,包含五个可以独立安装、独立发现、明确声明调用边界的 Skill。包内 `SKILL.md` 仍是行为权威;本 README 与用户指南负责说明使用方式。 -> **About:** Personal Skills Collection — Drive your creativity +> **简介:** Personal Skills Collection — Drive your creativity -> **Release:** [v0.1.1](https://github.com/LightDevCoder/skills/releases/tag/v0.1.1) +> **发布:** [v0.1.1](https://github.com/LightDevCoder/skills/releases/tag/v0.1.1) > 已从 commit `c50f1ef` 发布。发布记录和 fresh-install 证据见 > [docs/evidence/releases/v0.1.1/](docs/evidence/releases/v0.1.1/)。 > -> 独立 `review-loop agent-skill` acceptance 仍为 `BLOCKED`;准确边界见发布收据。 +> **发布状态:** 集合已发布且可使用。五个第一方 Skill 的安装与 +> `collection-quality` 检查均已通过。当前剩余的发布验收限制是 +> `review-loop agent-skill` 的独立 evaluator 证据:由于尚未附上 fresh +> independent evaluator record,该项仍为 `BLOCKED`。这不影响安装或一般使用; +> 详细边界见[发布收据](docs/evidence/releases/v0.1.1/RELEASE_RECEIPT.zh-CN.md) +> 和[限制说明](docs/evidence/releases/v0.1.1/LIMITATIONS.zh-CN.md)。 ## Quick Start @@ -28,7 +33,7 @@ npx skills add LightDevCoder/skills#v0.1.1 --yes --copy --agent codex npx skills add LightDevCoder/skills#v0.1.1 --skill review-loop --yes --copy --agent codex ``` -刷新 Agent host,然后在其 Skill catalog 中确认发现结果。若 host 提供文件系统,检查已安装包的 `SKILL.md` 与 `agents/openai.yaml`;脱离 source checkout 后仍能发现,才是有意义的验证。CLI 版本、destination 和结果见 [INSTALLATION_VERIFICATION.md](docs/evidence/releases/v0.1.1/INSTALLATION_VERIFICATION.md)。 +刷新 Agent host,然后在其 Skill catalog 中确认发现结果。若 host 提供文件系统,检查已安装包的 `SKILL.md` 与 `agents/openai.yaml`;脱离 source checkout 后仍能发现,才是有意义的验证。CLI 版本、destination 和结果见 [INSTALLATION_VERIFICATION.zh-CN.md](docs/evidence/releases/v0.1.1/INSTALLATION_VERIFICATION.zh-CN.md)。 第一次不知道下一步时,推荐显式调用 `$ask-light`: @@ -39,21 +44,38 @@ $ask-light next 三个最短示例: ```text -$ask-light next # 推荐下一 Skill,不执行它 +$ask-light next # 推荐下一 Skill,不执行 $project-init # 初始化已确认的最小项目 preset $review-loop init # 冻结已有验收标准的 baseline ``` -`ask-light` 只返回建议或一个有边界的 recipe,然后停止;不会执行、安装或自动串联。阅读 [Quick Start](examples/quick-start/README.zh-CN.md)、[Skill 使用指南](docs/zh-CN/skills/)、[workflow recipes](docs/zh-CN/workflows/) 了解输入、输出、handoff 和停止点。 +`ask-light` 只返回建议或一个有边界的 recipe,然后停止;不会执行、安装或自动串联。阅读 [Quick Start](examples/quick-start/README.zh-CN.md)、[Skill 使用指南](docs/zh-CN/skills/)、[工作流 recipes](docs/zh-CN/workflows/) 了解输入、输出、handoff 和停止点。 + +## 外部能力(External Capabilities) + +上面的五个包组成 Core collection:安装本仓库后即可使用目录中的五个第一方 Skill。 + +以下是可选的 workflow 能力,来自外部或第三方来源,不属于默认集合: + +- `grill-me` / `grilling`:`grill-me` 是一次会话澄清访谈的用户入口,会启动底层的 model-invoked `grilling` 能力。应把它们视为同一个能力,不要当成两个重复的工作流步骤。 +- `research`:本地 preset 不足时,用于调查外部事实或实践。 +- `to-spec`:把已确认的目标和约束整理成可追踪的 specification。 +- `to-tickets`:把已批准的 specification 整理成按依赖排序的 tickets。 +- `implement`:执行一个有边界且未被阻塞的 implementation ticket。 +- `code-review`:为固定变更提供 specialist findings。 +- `handoff`:为 closeout 或后续 resume 保存已接受结果或 blocker。 + +这些能力可能来自 `mattpocock/skills` 或其他外部来源。本仓库不复制这些 Skill, +也不会自动安装;选择包含它们的 workflow 前,请先确认当前 host 能看到对应能力。 ## 第一方目录 | Skill | 作用 | 调用方式 | 包路径 | | --- | --- | --- | --- | | [review-loop](skills/review-loop/SKILL.md) | 执行有边界的证据、修复和最终验收循环。 | Model-invoked;支持手动入口。 | skills/review-loop/ | -| [project-init](skills/project-init/SKILL.md) | 从最小 preset 初始化已确认的软件、文稿、研究、知识、数据或 Skill-development 项目。 | User-invoked only。 | skills/project-init/ | -| [ask-light](skills/ask-light/SKILL.md) | 检查 host 并推荐一个下一 Skill 或 bounded recipe,不执行建议。 | User-invoked only。 | skills/ask-light/ | -| [learn-anything](skills/learn-anything/SKILL.md) | 从有足够证据的资料中提炼可复用 Agent Skill 方法。 | User-invoked only。 | skills/learn-anything/ | +| [project-init](skills/project-init/SKILL.md) | 从最小 preset 初始化已确认的软件、文稿、研究、知识、数据或 Skill-development 项目。 | 仅 user-invoked。 | skills/project-init/ | +| [ask-light](skills/ask-light/SKILL.md) | 检查 host 并推荐一个下一 Skill 或 bounded recipe,不执行建议。 | 仅 user-invoked。 | skills/ask-light/ | +| [learn-anything](skills/learn-anything/SKILL.md) | 从有足够证据的资料中提炼可复用 Agent Skill 方法。 | 仅 user-invoked。 | skills/learn-anything/ | | [manuscript-ops](skills/manuscript-ops/SKILL.md) | 治理跨格式、批次、审查和 handoff 的可复现文稿工程。 | Model-invoked;支持手动入口。 | skills/manuscript-ops/ | 完整目录见 [CATALOG.zh-CN.md](CATALOG.zh-CN.md)。组合示例是文档和验证资产,不是固定 pipeline,也不是自动编排器;退休的 `project-workflow` 不会重新引入。 diff --git a/docs/INSTALLATION.zh-CN.md b/docs/INSTALLATION.zh-CN.md index c648f03..514fe26 100644 --- a/docs/INSTALLATION.zh-CN.md +++ b/docs/INSTALLATION.zh-CN.md @@ -2,7 +2,7 @@ [English installation guide](INSTALLATION.md) -公开第一方集合当前稳定版本是 [v0.1.1](https://github.com/LightDevCoder/skills/releases/tag/v0.1.1),commit 为 `c50f1ef403a5f0bfe02e75d1aeff2c237556db63`。已发布 tag 的 fresh-install 证据见[release evidence](evidence/releases/v0.1.1/)。`skills//` 内的包契约仍是行为权威;本页只规定安装和验证证据。 +公开第一方集合当前稳定版本是 [v0.1.1](https://github.com/LightDevCoder/skills/releases/tag/v0.1.1),commit 为 `c50f1ef403a5f0bfe02e75d1aeff2c237556db63`。已发布 tag 的 fresh-install 证据见[发布证据](evidence/releases/v0.1.1/RELEASE_RECEIPT.zh-CN.md)。`skills//` 内的包契约仍是行为权威;本页只规定安装和验证证据。 ## Revision 语义 @@ -30,7 +30,7 @@ npx skills add LightDevCoder/skills#v0.1.1 --yes --copy --agent codex npx skills add LightDevCoder/skills#v0.1.1 --skill review-loop --yes --copy --agent codex ``` -第一条安装五个包,第二条选择同一 tag 下的完整单包。已验证的 CLI version、destination 类别、discovery 和 smoke result 见 [v0.1.1 安装记录](evidence/releases/v0.1.1/INSTALLATION_VERIFICATION.md)。 +第一条安装五个包,第二条选择同一 tag 下的完整单包。已验证的 CLI version、destination 类别、discovery 和 smoke result 见 [v0.1.1 安装记录](evidence/releases/v0.1.1/INSTALLATION_VERIFICATION.zh-CN.md)。 ## 安装范围 diff --git a/docs/MAINTENANCE.zh-CN.md b/docs/MAINTENANCE.zh-CN.md index 87fd966..b7bdfc7 100644 --- a/docs/MAINTENANCE.zh-CN.md +++ b/docs/MAINTENANCE.zh-CN.md @@ -14,10 +14,10 @@ 新增、更新、改名、弃用或移除时: -1. 先执行 [Skill 准入](SKILL_ADMISSION.md) 的 reuse-before-invention 与 ownership gate。 +1. 先执行 [Skill 准入](SKILL_ADMISSION.zh-CN.md) 的 reuse-before-invention 与 ownership gate。 2. 保留包边界、invocation direction、attribution 和必要资源。 3. 收集 structural、fresh-install、behavioral、invocation、script 和 review evidence,并准确标注 evidence class。 -4. 执行 [review policy](REVIEW_POLICY.md) 的 review trigger。 +4. 执行[审查策略](REVIEW_POLICY.zh-CN.md)的 review trigger。 5. 同步 README、目录、安装说明、治理链接、affected recipes、discovery tests、attribution 和 changelog。 6. 未通过真实 release gate 前,不把版本、tag 或安装命令写成已验证。 diff --git a/docs/evidence/releases/v0.1.1/RELEASE_RECEIPT.zh-CN.md b/docs/evidence/releases/v0.1.1/RELEASE_RECEIPT.zh-CN.md index c298fca..157b729 100644 --- a/docs/evidence/releases/v0.1.1/RELEASE_RECEIPT.zh-CN.md +++ b/docs/evidence/releases/v0.1.1/RELEASE_RECEIPT.zh-CN.md @@ -19,15 +19,15 @@ Actions 和 fresh-install 证据已核验;独立 `review-loop agent-skill` acc ## 证据 -- 结构与 discovery:[DISCOVERY_VERIFICATION.md](DISCOVERY_VERIFICATION.md) -- 包与集合测试:[TEST_SUMMARY.md](TEST_SUMMARY.md) -- Fresh install 与 host discovery:[INSTALLATION_VERIFICATION.md](INSTALLATION_VERIFICATION.md) -- 限制和 evidence labels:[LIMITATIONS.md](LIMITATIONS.md) -- [审查策略](../../../REVIEW_POLICY.md) -- [准入契约](../../../SKILL_ADMISSION.md) - -| Fresh whole-repository install | `VERIFIED` | 见 [INSTALLATION_VERIFICATION.md](INSTALLATION_VERIFICATION.md)。 | -| Fresh per-Skill install | `VERIFIED` | 见 [INSTALLATION_VERIFICATION.md](INSTALLATION_VERIFICATION.md)。 | +- 结构与 discovery:[DISCOVERY_VERIFICATION.zh-CN.md](DISCOVERY_VERIFICATION.zh-CN.md) +- 包与集合测试:[TEST_SUMMARY.zh-CN.md](TEST_SUMMARY.zh-CN.md) +- Fresh install 与 host discovery:[INSTALLATION_VERIFICATION.zh-CN.md](INSTALLATION_VERIFICATION.zh-CN.md) +- 限制和 evidence labels:[LIMITATIONS.zh-CN.md](LIMITATIONS.zh-CN.md) +- [审查策略](../../../REVIEW_POLICY.zh-CN.md) +- [准入契约](../../../SKILL_ADMISSION.zh-CN.md) + +| Fresh whole-repository install | `VERIFIED` | 见 [INSTALLATION_VERIFICATION.zh-CN.md](INSTALLATION_VERIFICATION.zh-CN.md)。 | +| Fresh per-Skill install | `VERIFIED` | 见 [INSTALLATION_VERIFICATION.zh-CN.md](INSTALLATION_VERIFICATION.zh-CN.md)。 | | Independent `review-loop agent-skill` acceptance | `BLOCKED` | 等待 fresh independent evaluator 记录;同一上下文不是独立证据。 | | GitHub Actions | `VERIFIED` | 合并后的 release commit 上的 workflow 已通过。 | diff --git a/docs/evidence/releases/v0.1.1/TEST_SUMMARY.zh-CN.md b/docs/evidence/releases/v0.1.1/TEST_SUMMARY.zh-CN.md index 36b9103..22dc686 100644 --- a/docs/evidence/releases/v0.1.1/TEST_SUMMARY.zh-CN.md +++ b/docs/evidence/releases/v0.1.1/TEST_SUMMARY.zh-CN.md @@ -17,7 +17,7 @@ | Quick Start | `powershell -File tests/quick-start-smoke-tests.ps1` | `PASS`;8 条断言。 | | Python 语法 | 只读 `ast.parse` 检查 | `PASS`;12 个 Python 文件解析通过且不写入字节码。 | | Python `compileall` | `python -m compileall -q skills tests` | 本地 `NOT PASSED`;沙箱拒绝写入现有受保护的 `__pycache__`,但合并 release commit `c50f1ef` 上的 GitHub Actions 同命令已通过。 | -| Tagged fresh install | `npx skills add LightDevCoder/skills#v0.1.1 ...` 加 `npx skills list` | `PASS`;CLI `1.5.20`,整仓 destination 列出 5 个包,单 Skill destination 列出 `review-loop`,且两个 source checkout 都不存在。见[安装证据](INSTALLATION_VERIFICATION.md)。 | +| Tagged fresh install | `npx skills add LightDevCoder/skills#v0.1.1 ...` 加 `npx skills list` | `PASS`;CLI `1.5.20`,整仓 destination 列出 5 个包,单 Skill destination 列出 `review-loop`,且两个 source checkout 都不存在。见[安装证据](INSTALLATION_VERIFICATION.zh-CN.md)。 | | Release-commit CI | GitHub Actions `collection-quality` | `PASS`;run `30189210521` 对应 `c50f1ef403a5f0bfe02e75d1aeff2c237556db63`。 | 包测试只证明覆盖到的 contract 场景;collection discovery 只证明 cross-reference 和 metadata 一致。tagged installation 证据另有记录;这些证据都不能证明 independent acceptance 或模型介导的 runtime 行为。 diff --git a/docs/skills/manuscript-ops.md b/docs/skills/manuscript-ops.md index 859ac8a..555f8ee 100644 --- a/docs/skills/manuscript-ops.md +++ b/docs/skills/manuscript-ops.md @@ -38,8 +38,10 @@ records, review evidence, and production QA records. ## Handoffs, success, and `BLOCKED` On a Project route, choose one discovery handoff: `grill-me` for one-session -decisions or `wayfinder` for multi-session uncertainty, then stop. Continue -only after the user explicitly resumes `manuscript-ops`. Before initialization, +decisions or `wayfinder` for multi-session uncertainty, then stop. `grill-me` +is the user-facing entry point; its underlying model-invoked capability is +`grilling`, so it is one clarification capability rather than two user steps. +Continue only after the user explicitly resumes `manuscript-ops`. Before initialization, the user must explicitly choose `project-init`; before review, an approved `review-loop` Charter is required. `BLOCKED` is correct for a missing root, missing dependency, unapproved brief, absent capability, missing evidence, or diff --git a/docs/skills/project-init.md b/docs/skills/project-init.md index 51dbbba..c7621f7 100644 --- a/docs/skills/project-init.md +++ b/docs/skills/project-init.md @@ -25,8 +25,9 @@ defaults to the current directory. Before writing, it reads root `AGENTS.md`/`CLAUDE.md`, README, manifests, project documents, and current status. It needs the project type, visible goal, outputs, collaboration mode, constraints, and required review level, either from the brief or from its -short questions. `grilling` may help answer missing questions; it does not -authorize additional writes. +short questions. Use the external user-facing `grill-me` entry point when a +question needs a clarification interview; its underlying model-invoked +capability is `grilling`. This does not authorize additional writes. ```text $project-init diff --git a/docs/workflows/recipes.md b/docs/workflows/recipes.md index 3be6211..85de26d 100644 --- a/docs/workflows/recipes.md +++ b/docs/workflows/recipes.md @@ -18,6 +18,10 @@ authority for every package. - **Private modified third-party:** a package in `skills-3rdParty`; an absent private root is an availability gap, not an invitation to invent a fallback. +`grill-me` is the user-facing entry point for one-session clarification. It +starts the underlying model-invoked `grilling` capability; treat them as one +external capability, not two separate user-facing workflow steps. + Each row declares the handoff artifact and stop condition. `user-invoked` means the user must explicitly select the Skill; `model-invoked` means the host may call it under its package policy. Findings from a specialist never become the diff --git a/docs/zh-CN/skills/ask-light.md b/docs/zh-CN/skills/ask-light.md index d041d52..1f7eff6 100644 --- a/docs/zh-CN/skills/ask-light.md +++ b/docs/zh-CN/skills/ask-light.md @@ -1,6 +1,6 @@ # `ask-light` 使用指南 -[English guide](../../skills/ask-light.md) +[英文指南](../../skills/ask-light.md) 行为与 scanner 输出契约见 [skills/ask-light/SKILL.md](../../../skills/ask-light/SKILL.md) 和 [discovery contract](../../../skills/ask-light/references/discovery-contract.md)。 diff --git a/docs/zh-CN/skills/learn-anything.md b/docs/zh-CN/skills/learn-anything.md index c979b69..24dafcd 100644 --- a/docs/zh-CN/skills/learn-anything.md +++ b/docs/zh-CN/skills/learn-anything.md @@ -1,6 +1,6 @@ # `learn-anything` 使用指南 -[English guide](../../skills/learn-anything.md) +[英文指南](../../skills/learn-anything.md) 唯一行为权威是 [skills/learn-anything/SKILL.md](../../../skills/learn-anything/SKILL.md)。 diff --git a/docs/zh-CN/skills/manuscript-ops.md b/docs/zh-CN/skills/manuscript-ops.md index 333e6d7..02a63b6 100644 --- a/docs/zh-CN/skills/manuscript-ops.md +++ b/docs/zh-CN/skills/manuscript-ops.md @@ -1,6 +1,6 @@ # `manuscript-ops` 使用指南 -[English guide](../../skills/manuscript-ops.md) +[英文指南](../../skills/manuscript-ops.md) 完整行为契约见 [skills/manuscript-ops/SKILL.md](../../../skills/manuscript-ops/SKILL.md)。 @@ -25,7 +25,7 @@ $manuscript-ops resume ## Handoff、成功和 `BLOCKED` -Project route 先按需要选择一个 discovery handoff:单会话决策用 `grill-me`,多会话不确定性用 `wayfinder`,随后停止;只有用户显式 resume 才能继续。初始化前需用户显式选择 `project-init`,review 前需批准的 `review-loop` Charter。root、dependency、brief、capability、证据或真实渲染/round-trip proof 缺失时返回 `BLOCKED`,不能把语法有效当成视觉验收。 +Project route 先按需要选择一个 discovery handoff:单会话决策用 `grill-me`,多会话不确定性用 `wayfinder`,随后停止。`grill-me` 是用户入口,底层的 model-invoked 能力是 `grilling`;二者是同一个澄清能力,不是两个用户步骤。只有用户显式 resume 才能继续。初始化前需用户显式选择 `project-init`,review 前需批准的 `review-loop` Charter。root、dependency、brief、capability、证据或真实渲染/round-trip proof 缺失时返回 `BLOCKED`,不能把语法有效当成视觉验收。 ## 组合和最终权威 diff --git a/docs/zh-CN/skills/project-init.md b/docs/zh-CN/skills/project-init.md index 210bfa0..9855e60 100644 --- a/docs/zh-CN/skills/project-init.md +++ b/docs/zh-CN/skills/project-init.md @@ -1,6 +1,6 @@ # `project-init` 使用指南 -[English guide](../../skills/project-init.md) +[英文指南](../../skills/project-init.md) 行为权威是 [skills/project-init/SKILL.md](../../../skills/project-init/SKILL.md)。 @@ -20,7 +20,7 @@ $project-init ## 前置条件、输入和输出 -默认目标是当前目录。写入前读取根部 `AGENTS.md`/`CLAUDE.md`、README、manifest、项目文档和当前状态。输入包括项目类型、用户目标、输出物、协作方式、约束和 review level;已有 brief 能回答时不重复询问。`grilling` 只能帮助澄清问题,不能授权额外写入。 +默认目标是当前目录。写入前读取根部 `AGENTS.md`/`CLAUDE.md`、README、manifest、项目文档和当前状态。输入包括项目类型、用户目标、输出物、协作方式、约束和 review level;已有 brief 能回答时不重复询问。需要澄清问题时使用外部的用户入口 `grill-me`;它启动底层 model-invoked 能力 `grilling`。这不能授权额外写入。 输出包括 preset 或已确认的 fallback、唯一 instruction target、变更路径、能力可用性、验证结果和后续 Skill 建议;不得创建 tickets、implementation plan、final-review record 或竞争性的 specification。 diff --git a/docs/zh-CN/skills/review-loop.md b/docs/zh-CN/skills/review-loop.md index 865ccc2..0bbc930 100644 --- a/docs/zh-CN/skills/review-loop.md +++ b/docs/zh-CN/skills/review-loop.md @@ -1,6 +1,6 @@ # `review-loop` 使用指南 -[English guide](../../skills/review-loop.md) +[英文指南](../../skills/review-loop.md) 行为权威仍是 [skills/review-loop/SKILL.md](../../../skills/review-loop/SKILL.md);本页只说明如何使用,不复制第二份契约。 @@ -36,4 +36,4 @@ $review-loop resume ## 安装与发现验证 -对于已发布的 v0.1.1,使用 `npx skills add LightDevCoder/skills#v0.1.1 --skill review-loop` 安装,刷新 host,在不依赖 source checkout 的情况下检查已发现的 `SKILL.md` 和 `agents/openai.yaml`。运行 [Profile tests](../../../skills/review-loop/tests/);结果记录在 [安装证据](../../evidence/releases/v0.1.1/INSTALLATION_VERIFICATION.md)。 +对于已发布的 v0.1.1,使用 `npx skills add LightDevCoder/skills#v0.1.1 --skill review-loop` 安装,刷新 host,在不依赖 source checkout 的情况下检查已发现的 `SKILL.md` 和 `agents/openai.yaml`。运行 [Profile tests](../../../skills/review-loop/tests/);结果记录在[安装证据](../../evidence/releases/v0.1.1/INSTALLATION_VERIFICATION.zh-CN.md)。 diff --git a/docs/zh-CN/workflows/README.md b/docs/zh-CN/workflows/README.md index 6cbd527..592e220 100644 --- a/docs/zh-CN/workflows/README.md +++ b/docs/zh-CN/workflows/README.md @@ -1,12 +1,12 @@ # 已验证组合示例 -[English workflow examples](../../workflows/README.md) +[英文版 workflow examples](../../workflows/README.md) 这里的文档用于展示 Skill 之间的安全组合、调用边界、停止点和证据。它们不是准入 gate、canonical workflow 或自动编排器,也不会自动调用其他 user-invoked Skill。 ## 当前示例 - [Ask Light 显式选择下一步](first-party-composition.md) -- [Workflow recipes](recipes.md) +- [工作流 recipes](recipes.md) -完整的第一方组合示例见 [English version](../../workflows/first-party-composition.md);当前五个包的 behavior authority 仍在各自 `SKILL.md`。 +完整的第一方组合示例见[英文版示例](../../workflows/first-party-composition.md);当前五个包的 behavior authority 仍在各自 `SKILL.md`。外部 workflow 能力不属于本仓库默认安装内容,且不会由这些示例自动安装。 diff --git a/docs/zh-CN/workflows/first-party-composition.md b/docs/zh-CN/workflows/first-party-composition.md index aaf8f31..ec58fc2 100644 --- a/docs/zh-CN/workflows/first-party-composition.md +++ b/docs/zh-CN/workflows/first-party-composition.md @@ -1,6 +1,6 @@ # Ask Light 显式选择下一步 -[English example](../../workflows/first-party-composition.md) +[英文版示例](../../workflows/first-party-composition.md) ## 场景 @@ -28,6 +28,6 @@ Agent 已有 goal、artifacts、blockers、project type、task kind、availabili - 五个包的 `SKILL.md`。 - [ask-light discovery contract](../../../skills/ask-light/references/discovery-contract.md)。 - [collection discovery test](../../../tests/collection-discovery-tests.ps1)。 -- [v0.1.1 release evidence](../../evidence/releases/v0.1.1/)。 +- [v0.1.1 发布证据](../../evidence/releases/v0.1.1/RELEASE_RECEIPT.zh-CN.md)。 -这是验证资产,不是 canonical workflow 或 admission requirement。 +这是验证资产,不是 canonical workflow 或准入要求。 diff --git a/docs/zh-CN/workflows/recipes.md b/docs/zh-CN/workflows/recipes.md index d9bc8de..f899e15 100644 --- a/docs/zh-CN/workflows/recipes.md +++ b/docs/zh-CN/workflows/recipes.md @@ -1,22 +1,24 @@ -# Workflow Recipes +# 工作流 Recipes -[English recipes](../../workflows/recipes.md) +[英文版 recipes](../../workflows/recipes.md) 这些 recipe 是有边界的文档和验证资产,只描述显式 handoff;不会创建 canonical pipeline、永久 state machine 或自动多 Skill orchestrator。每个包的 `SKILL.md` 仍是行为权威。 ## 来源与共同规则 -- **First-party:** 本仓库的 `review-loop`、`project-init`、`ask-light`、`learn-anything`、`manuscript-ops`。 -- **Matt upstream:** `mattpocock/skills` 中的 `to-spec`、`to-tickets`、`implement`、`code-review`、`handoff`、`diagnosing-bugs`、`grill-me`、`wayfinder`、`writing-great-skills`,或可见的 pinned third-party package。 -- **Private modified third-party:** `skills-3rdParty` 内的包;私有 root 不可见时必须报告 availability gap,不能编造 fallback。 +- **第一方(First-party):** 本仓库的 `review-loop`、`project-init`、`ask-light`、`learn-anything`、`manuscript-ops`。 +- **Matt 上游(Matt upstream):** `mattpocock/skills` 中的 `to-spec`、`to-tickets`、`implement`、`code-review`、`handoff`、`diagnosing-bugs`、`grill-me`、`wayfinder`、`writing-great-skills`,或可见的 pinned third-party package。 +- **私有第三方修改版(Private modified third-party):** `skills-3rdParty` 内的包;私有 root 不可见时必须报告 availability gap,不能编造 fallback。 每行都写明 handoff artifact 和 stop condition。`user-invoked` 必须由用户显式选择;`model-invoked` 仍受包自身 policy 约束。specialist findings 不能成为最终 verdict;需要验收时由 `review-loop` 拥有 `PASS`、`FAIL`、`BLOCKED`。 +`grill-me` 是一次会话澄清的用户入口,会启动底层的 model-invoked `grilling` 能力。二者属于同一个外部能力,不是两个需要用户分别选择的工作流步骤。 + ## 1. 软件项目 -**Entry condition:** 软件 feature/implementation 的目标、约束和验收方向已经明确。 +**入口条件:** 软件 feature/implementation 的目标、约束和验收方向已经明确。 -顺序为 `to-spec`(Matt upstream,user-invoked)→ `review-loop` specification(first-party,model-invoked)→ `to-tickets`(Matt upstream,user-invoked)→ `implement`(Matt upstream,user-invoked)→ `code-review`(Matt upstream,model-invoked,只提供 specialist findings)→ `review-loop` software(first-party,拥有最终 verdict)→ `handoff`(Matt upstream,user-invoked)。每一步的输入、输出、handoff 和 stop condition 见 [English recipe](../../workflows/recipes.md#1-software-feature)。 +顺序为 `to-spec`(Matt upstream,user-invoked)→ `review-loop` specification(first-party,model-invoked)→ `to-tickets`(Matt upstream,user-invoked)→ `implement`(Matt upstream,user-invoked)→ `code-review`(Matt upstream,model-invoked,只提供 specialist findings)→ `review-loop` software(first-party,拥有最终 verdict)→ `handoff`(Matt upstream,user-invoked)。每一步的输入、输出、handoff 和 stop condition 见[英文 recipe](../../workflows/recipes.md#1-software-feature)。 缺少 acceptance authority、上游 Skill、批准 ticket、实现依赖或 independent evaluator 时 `BLOCKED`。证据包括 spec、ticket graph、commit、focused tests、specialist findings、review-loop state/verdict 和 handoff;到 `PASS`/`FAIL`/`BLOCKED` 停止。 @@ -26,7 +28,7 @@ ## 3. 文稿项目 -顺序为 `manuscript-ops` → 按需选择 `grill-me`/`wayfinder` → `project-init` → `review-loop init` → manuscript production → `review-loop` manuscript Profile。Project route 选择 discovery handoff 后必须停;只有用户显式 `resume` 才能继续。root、dependency、brief、Charter、render/round-trip evidence 缺失时 `BLOCKED`,最终 verdict 归 `review-loop`。 +顺序为 `manuscript-ops` → 按需选择 `grill-me`/`wayfinder` → `project-init` → `review-loop init` → manuscript production → `review-loop` manuscript Profile。这里的 `grill-me` 是用户入口,底层 `grilling` 不作为第二个用户步骤单独选择。Project route 选择 discovery handoff 后必须停;只有用户显式 `resume` 才能继续。root、dependency、brief、Charter、render/round-trip evidence 缺失时 `BLOCKED`,最终 verdict 归 `review-loop`。 ## 4. 从资料提炼 Skill diff --git a/examples/quick-start/README.zh-CN.md b/examples/quick-start/README.zh-CN.md index e5000b1..081d696 100644 --- a/examples/quick-start/README.zh-CN.md +++ b/examples/quick-start/README.zh-CN.md @@ -1,8 +1,10 @@ # Quick Start 示例 -[English version](README.md) +[英文版](README.md) -这个小示例展示第一方集合的显式选择边界。它是文档 fixture,不是 workflow,也不是已经执行过命令的证明。 +这个小示例展示第一方集合的显式选择边界。它是文档 fixture,不是 workflow,也不是已经执行过命令的证明。理解本页流程不要求先阅读英文版的 `brief.md` 或 `AGENTS.md`;所需上下文已在下面说明。 + +本示例的上下文是:目标是准备一份有来源支持、可检查的小型文档实验 brief;唯一提供的 artifact 是 `brief.md`,当前没有实现文件;用户尚未批准 specification、ticket graph 或 final acceptance source。第一步只是在 `$ask-light` 与 `$project-init` 之间做显式选择,不授权自动串联或发布。 ## 1. 安装 @@ -20,7 +22,7 @@ npx skills add LightDevCoder/skills#v0.1.1 --skill ask-light ## 2. 查看示例 -阅读 [brief.md](brief.md) 和 [AGENTS.md](AGENTS.md)。它们只提供足够让 Agent 选择入口的上下文,不授权写业务代码,也不会静默串联 Skill。 +本页已经包含选择入口所需的上下文,不需要阅读英文文件才能继续。若要核对原始 fixture,可选阅读 [brief.md](brief.md) 和 [AGENTS.md](AGENTS.md);它们只补充同一边界,不授权写业务代码,也不会静默串联 Skill。 ## 3. 显式调用 @@ -30,7 +32,7 @@ $project-init $review-loop init using brief.md ``` -只选择与当前状态匹配的命令。预期结果是可检查的建议、最小初始化报告或 review Charter/state。下面是 Illustrative output / 示意输出,不代表本仓库已经运行: +只选择与当前状态匹配的命令。预期结果是可检查的建议、最小初始化报告或 review Charter/state。以下是 Illustrative output(示意输出),不代表本仓库已经运行: ```text Status: RECOMMEND @@ -39,4 +41,4 @@ Execution: recommendation only; nothing was invoked, installed, or orchestrated ## 4. 停止并 handoff -`$ask-light` 后停止并等待用户选择;`$project-init` 后在 discovery/specification/implementation/final review 前停止;`$review-loop` 后在持久化的 `PASS`、`FAIL` 或 `BLOCKED` verdict 停止。stop after each handoff / 每个 handoff 后停止。更长的组合见 [workflow recipes](../../docs/zh-CN/workflows/recipes.md),真实 release 验证见 [fresh-install evidence](../../docs/evidence/releases/v0.1.1/INSTALLATION_VERIFICATION.md)。 +`$ask-light` 后停止并等待用户选择;`$project-init` 后在 discovery/specification/implementation/final review 前停止;`$review-loop` 后在持久化的 `PASS`、`FAIL` 或 `BLOCKED` verdict 停止。每个 handoff 后都要停止并保留状态。更长的组合见[工作流 recipes](../../docs/zh-CN/workflows/recipes.md),真实 release 验证见[安装证据](../../docs/evidence/releases/v0.1.1/INSTALLATION_VERIFICATION.zh-CN.md)。 diff --git a/skills/manuscript-ops/SKILL.md b/skills/manuscript-ops/SKILL.md index f015195..8c3d004 100644 --- a/skills/manuscript-ops/SKILL.md +++ b/skills/manuscript-ops/SKILL.md @@ -5,6 +5,10 @@ description: Route and govern manuscript engineering from small notes and struct # Manuscript Ops +For one-session clarification, `grill-me` is the external user-facing entry +point and `grilling` is its underlying model-invoked capability. Treat them as +one discovery handoff, not two separate user-facing steps. + Treat the manuscript as a governed state machine, not a single editable file. Keep source authority, user decisions, reproducible generation, review evidence, and human gates visible throughout the work. diff --git a/skills/manuscript-ops/references/handoffs.md b/skills/manuscript-ops/references/handoffs.md index ab749f1..b96134c 100644 --- a/skills/manuscript-ops/references/handoffs.md +++ b/skills/manuscript-ops/references/handoffs.md @@ -18,7 +18,8 @@ contract as well. Do not use `--audit-all` in an ordinary manuscript handoff; it changes audit scope, not the selected workflow branch. Use `--strict-agent-skills` on a client that rejects non-standard frontmatter. -The pinned `grill-me` and `wayfinder` contracts currently use +The pinned `grill-me` user entry starts the underlying `grilling` capability; +the `grill-me` and `wayfinder` contracts currently use `disable-model-invocation`; a strict client must return `BLOCKED` unless it has compatible releases or an explicit host extension. @@ -109,8 +110,9 @@ $manuscript-ops resume from /.review-loop/state.md Install and refresh the agent between layers when necessary: -1. Required discovery closure from `mattpocock/skills`: `grill-me`, `grilling`, - `wayfinder`, and `domain-modeling`. +1. Required discovery closure from `mattpocock/skills`: `grill-me` (the user + entry), its underlying `grilling` capability, `wayfinder`, and + `domain-modeling`. 2. Optional Wayfinder branches, before they are selected: `prototype` and `setup-matt-pocock-skills`. 3. Independent acceptance from `LightDevCoder/Agent-Workflow`: diff --git a/skills/project-init/SKILL.md b/skills/project-init/SKILL.md index 78a0781..76c3178 100644 --- a/skills/project-init/SKILL.md +++ b/skills/project-init/SKILL.md @@ -32,8 +32,9 @@ Skill is a reportable capability gap, not a reason to invent a command. ### 2. Ask lightweight project questions -Use `grilling` as a model-invoked capability when answers are not already -explicit. Ask one short question at a time and capture six answers: +Use the external user-facing `grill-me` entry point when answers are not +already explicit. `grill-me` starts the underlying model-invoked `grilling` +capability; treat this as one clarification capability. Ask one short question at a time and capture six answers: 1. project type; 2. user-visible goal; @@ -109,6 +110,7 @@ confirmation decision if research was used. This Skill does not run `to-spec`, `to-tickets`, `implement`, `final review`, `review-loop`, `ask-light`, `learn-anything`, or any other user-invoked Skill. It does not manage tickets, perform implementation, establish acceptance, or -become a permanent project workflow manager. `grilling` and `research` above -are model-invoked capabilities permitted only for the stated questions and -confirmed fallback; they do not authorize additional writes. +become a permanent project workflow manager. `grill-me` (through its underlying +`grilling` capability) and `research` above are external capabilities permitted +only for the stated questions and confirmed fallback; they do not authorize +additional writes. diff --git a/skills/project-init/references/initialization-contract.md b/skills/project-init/references/initialization-contract.md index 7d2c0e4..ca7b235 100644 --- a/skills/project-init/references/initialization-contract.md +++ b/skills/project-init/references/initialization-contract.md @@ -38,8 +38,10 @@ Record skipped checks and optional documents explicitly. ## Capability and invocation boundary -`grilling` and `research` are model-invoked capabilities allowed by this -initializer. The user remains in control of `to-spec`, `to-tickets`, +`grill-me` is the user-facing entry point for the model-invoked `grilling` +capability; together they provide the clarification interview allowed by this +initializer. `research` is another model-invoked capability allowed for the +confirmed fallback. The user remains in control of `to-spec`, `to-tickets`, `implement`, `review-loop`, `ask-light`, `learn-anything`, and every other user-invoked Skill. Project-init may recommend those names but never executes or orchestrates them. diff --git a/skills/review-loop/references/attribution.md b/skills/review-loop/references/attribution.md index b895e40..2661cb1 100644 --- a/skills/review-loop/references/attribution.md +++ b/skills/review-loop/references/attribution.md @@ -7,8 +7,9 @@ licensed projects: especially its execution gates, bounded agent packets, smoke-test evidence, snapshots, closeout, and advisory review gate. - [mattpocock/skills](https://github.com/mattpocock/skills), especially - `grill-me`, `grilling`, and `wayfinder` for the boundary between decision - discovery, planning, and execution. + `grill-me` as the user entry to its underlying `grilling` capability, and + `wayfinder` for the boundary between decision discovery, planning, and + execution. The audited projects are credited to their respective authors under MIT. No source text, code, visual asset, task-board implementation, or license text was