From 9649354c5766225fb5b59288a15e99344b37af56 Mon Sep 17 00:00:00 2001 From: NuoJin <1430093320@qq.com> Date: Wed, 25 Mar 2026 21:11:18 +0800 Subject: [PATCH 1/2] docs: streamline continuity suite installation --- .../plans/2026-03-25-continuity-install-ux.md | 229 ++++++++++++++++++ skills/skill-task-continuity/README.md | 30 ++- skills/skill-task-continuity/README.zh-CN.md | 30 ++- .../references/composition-guide.md | 9 + .../references/composition-guide.zh-CN.md | 9 + .../references/install-playbook.md | 34 ++- .../references/install-playbook.zh-CN.md | 34 ++- .../tests/test_docs_contract.py | 57 +++++ 8 files changed, 420 insertions(+), 12 deletions(-) create mode 100644 docs/superpowers/plans/2026-03-25-continuity-install-ux.md create mode 100644 skills/skill-task-continuity/tests/test_docs_contract.py diff --git a/docs/superpowers/plans/2026-03-25-continuity-install-ux.md b/docs/superpowers/plans/2026-03-25-continuity-install-ux.md new file mode 100644 index 0000000..2bed172 --- /dev/null +++ b/docs/superpowers/plans/2026-03-25-continuity-install-ux.md @@ -0,0 +1,229 @@ +# Continuity Install UX Implementation Plan + +> **For agentic workers:** REQUIRED SUB-SKILL: Use superpowers:subagent-driven-development (recommended) or superpowers:executing-plans to implement this plan task-by-task. Steps use checkbox (`- [ ]`) syntax for tracking. + +**Goal:** Make the long-task continuity suite easier to adopt by documenting a one-command full-suite install path, preferring natural-language Codex invocation for bootstrap, and tightening the atomic package README guidance. + +**Architecture:** Keep package boundaries unchanged and avoid implicit multi-package installation side effects. Reuse the existing `skill-installer` capability to accept multiple `--path` values, then document that clearly in `skill-task-continuity`. Add lightweight documentation-contract tests so future README edits do not regress installation or natural-language usage guidance. + +**Tech Stack:** Markdown package docs, Python `unittest`, existing `skill-installer` behavior, existing continuity package structure under `skills/` + +--- + +## File Map + +- Modify: `skills/skill-task-continuity/README.md` + - Add “install just this package” vs “install the full suite” guidance. + - Add natural-language Codex installation and bootstrap wording. +- Modify: `skills/skill-task-continuity/README.zh-CN.md` + - Mirror the English changes in Chinese. +- Modify: `skills/skill-task-continuity/references/install-playbook.md` + - Rework bootstrap guidance so natural-language Codex invocation is the first path and CLI is the precise fallback. +- Modify: `skills/skill-task-continuity/references/install-playbook.zh-CN.md` + - Mirror the English playbook changes in Chinese. +- Modify: `skills/skill-task-continuity/references/composition-guide.md` + - Add an explicit one-command full-suite install example and suite-entry wording if needed. +- Modify: `skills/skill-task-continuity/references/composition-guide.zh-CN.md` + - Mirror the English composition-guide changes in Chinese. +- Create: `skills/skill-task-continuity/tests/test_docs_contract.py` + - Lock in suite install UX and natural-language bootstrap wording. +- Modify: `skills/skill-context-keeper/README.md` + - Add direct natural-language “ask Codex to use this skill” usage guidance. +- Modify: `skills/skill-context-keeper/README.zh-CN.md` + - Mirror the English usage guidance in Chinese. +- Modify: `skills/skill-phase-gate/README.md` + - Add direct natural-language “ask Codex to use this skill” usage guidance. +- Modify: `skills/skill-phase-gate/README.zh-CN.md` + - Mirror the English usage guidance in Chinese. +- Modify: `skills/skill-handoff-summary/README.md` + - Add direct natural-language “ask Codex to use this skill” usage guidance. +- Modify: `skills/skill-handoff-summary/README.zh-CN.md` + - Mirror the English usage guidance in Chinese. +- Modify: `skills/skill-context-keeper/tests/test_package_contract.py` + - Assert the README contains direct natural-language usage guidance. +- Modify: `skills/skill-phase-gate/tests/test_package_contract.py` + - Assert the README contains direct natural-language usage guidance. +- Modify: `skills/skill-handoff-summary/tests/test_package_contract.py` + - Assert the README contains direct natural-language usage guidance. + +## Approved Design Notes + +- Use the existing `skill-installer --path ...` behavior for full-suite installation. +- Do **not** make `skill-task-continuity` auto-install the three atomic skills. +- Prefer natural-language Codex enable/bootstrap wording in package docs, with shell commands retained as exact execution fallbacks. +- Tighten the atomic package READMEs only where it materially improves “how do I actually use this with Codex?” clarity. + +### Task 1: Add Suite Documentation Contract Tests + +**Files:** +- Create: `skills/skill-task-continuity/tests/test_docs_contract.py` +- Test: `skills/skill-task-continuity/tests/test_docs_contract.py` + +- [ ] **Step 1: Write the failing documentation-contract tests** + +Add tests that assert: +- the suite README mentions installing the whole suite in one command +- the full-suite install path uses multiple `--path` values instead of implicit side effects +- the install playbook mentions asking Codex in natural language to bootstrap a downstream repo +- the playbook still preserves explicit CLI fallback examples + +- [ ] **Step 2: Run the new tests to verify they fail** + +Run: `cd /home/jn/projects/codex/codex-skill-library/.worktrees/continuity-install-ux && python3 -m unittest discover -s skills/skill-task-continuity/tests -p 'test_docs_contract.py' -v` +Expected: FAIL because the current docs do not yet contain the new full-suite install and natural-language bootstrap wording. + +- [ ] **Step 3: Commit the failing-test checkpoint only if you want a visible TDD breadcrumb** + +```bash +git add skills/skill-task-continuity/tests/test_docs_contract.py +git commit -m "test: add continuity install ux doc contracts" +``` + +### Task 2: Implement Suite Install And Bootstrap Documentation Changes + +**Files:** +- Modify: `skills/skill-task-continuity/README.md` +- Modify: `skills/skill-task-continuity/README.zh-CN.md` +- Modify: `skills/skill-task-continuity/references/install-playbook.md` +- Modify: `skills/skill-task-continuity/references/install-playbook.zh-CN.md` +- Modify: `skills/skill-task-continuity/references/composition-guide.md` +- Modify: `skills/skill-task-continuity/references/composition-guide.zh-CN.md` +- Test: `skills/skill-task-continuity/tests/test_docs_contract.py` + +- [ ] **Step 1: Update the suite README files** + +Add: +- a “just this package” install path +- a one-command “install the full suite” path using multiple `--path` arguments +- natural-language Codex install wording +- natural-language Codex bootstrap wording before the shell commands + +- [ ] **Step 2: Update the install playbooks** + +Rework the bootstrap walkthrough so it says, in plain language, how to ask Codex to: +- install the suite entry package +- install all four continuity packages together when desired +- preview downstream bootstrap changes +- run the real bootstrap + +Retain the existing shell commands as precise alternatives. + +- [ ] **Step 3: Update the composition guides if needed** + +Make sure the suite package now clearly says: +- one package can teach and bootstrap the suite +- one command can install all four packages +- atomic packages still own the actual task actions + +- [ ] **Step 4: Re-run the suite documentation-contract tests** + +Run: `cd /home/jn/projects/codex/codex-skill-library/.worktrees/continuity-install-ux && python3 -m unittest discover -s skills/skill-task-continuity/tests -p 'test_docs_contract.py' -v` +Expected: PASS + +- [ ] **Step 5: Commit the suite install UX changes** + +```bash +git add skills/skill-task-continuity/README.md skills/skill-task-continuity/README.zh-CN.md skills/skill-task-continuity/references/install-playbook.md skills/skill-task-continuity/references/install-playbook.zh-CN.md skills/skill-task-continuity/references/composition-guide.md skills/skill-task-continuity/references/composition-guide.zh-CN.md skills/skill-task-continuity/tests/test_docs_contract.py +git commit -m "docs: streamline continuity suite install guidance" +``` + +### Task 3: Tighten Atomic Package “Use It With Codex” Guidance + +**Files:** +- Modify: `skills/skill-context-keeper/README.md` +- Modify: `skills/skill-context-keeper/README.zh-CN.md` +- Modify: `skills/skill-phase-gate/README.md` +- Modify: `skills/skill-phase-gate/README.zh-CN.md` +- Modify: `skills/skill-handoff-summary/README.md` +- Modify: `skills/skill-handoff-summary/README.zh-CN.md` +- Modify: `skills/skill-context-keeper/tests/test_package_contract.py` +- Modify: `skills/skill-phase-gate/tests/test_package_contract.py` +- Modify: `skills/skill-handoff-summary/tests/test_package_contract.py` + +- [ ] **Step 1: Add failing README contract checks for direct natural-language usage** + +Extend the package-contract tests so each README must contain at least one direct “ask Codex to use this skill” phrasing, not just install wording and links to prompt templates. + +- [ ] **Step 2: Run the three package-contract test files and verify they fail** + +Run: +```bash +cd /home/jn/projects/codex/codex-skill-library/.worktrees/continuity-install-ux +python3 -m unittest discover -s skills/skill-context-keeper/tests -p 'test_package_contract.py' -v +python3 -m unittest discover -s skills/skill-phase-gate/tests -p 'test_package_contract.py' -v +python3 -m unittest discover -s skills/skill-handoff-summary/tests -p 'test_package_contract.py' -v +``` +Expected: at least one FAIL per package before the README updates land. + +- [ ] **Step 3: Update the three atomic package README pairs** + +For each package, add a short, direct section or paragraph that shows how to tell Codex to use the skill in natural language. + +Keep the package boundaries intact: +- `skill-context-keeper` = state refresh only +- `skill-phase-gate` = checkpoint only +- `skill-handoff-summary` = handoff only + +- [ ] **Step 4: Re-run the three package-contract test files** + +Run the same three `python3 -m unittest discover ...` commands from Step 2. +Expected: PASS + +- [ ] **Step 5: Commit the atomic README clarity pass** + +```bash +git add skills/skill-context-keeper/README.md skills/skill-context-keeper/README.zh-CN.md skills/skill-phase-gate/README.md skills/skill-phase-gate/README.zh-CN.md skills/skill-handoff-summary/README.md skills/skill-handoff-summary/README.zh-CN.md skills/skill-context-keeper/tests/test_package_contract.py skills/skill-phase-gate/tests/test_package_contract.py skills/skill-handoff-summary/tests/test_package_contract.py +git commit -m "docs: clarify continuity skill invocation wording" +``` + +### Task 4: Full Verification And Release-Safe Wrap-Up + +**Files:** +- Verify only: `skills/skill-task-continuity/tests/test_docs_contract.py` +- Verify only: `skills/skill-context-keeper/tests/test_package_contract.py` +- Verify only: `skills/skill-phase-gate/tests/test_package_contract.py` +- Verify only: `skills/skill-handoff-summary/tests/test_package_contract.py` +- Verify only: `evals/test_run_evals.py` +- Verify only: `evals/cases.csv` + +- [ ] **Step 1: Run the continuity package tests** + +Run: +```bash +cd /home/jn/projects/codex/codex-skill-library/.worktrees/continuity-install-ux +for test_dir in skills/*/tests; do + python3 -m unittest discover -s "$test_dir" -p 'test_*.py' -v +done +``` +Expected: all package tests PASS + +- [ ] **Step 2: Run the additional governance validation** + +Run: `cd /home/jn/projects/codex/codex-skill-library/.worktrees/continuity-install-ux/skills/skill-governance && python3 scripts/manage_skill.py --validate-only` +Expected: `[OK] Validation passed` + +- [ ] **Step 3: Run eval unit tests** + +Run: `cd /home/jn/projects/codex/codex-skill-library/.worktrees/continuity-install-ux && python3 -m unittest discover -s evals -p 'test_*.py' -v` +Expected: PASS + +- [ ] **Step 4: Run the continuity eval seed matrix** + +Run: `cd /home/jn/projects/codex/codex-skill-library/.worktrees/continuity-install-ux && python3 evals/run_evals.py` +Expected: `Cases: 8 Passed: 8 Failed: 0` + +- [ ] **Step 5: Check git state and prepare summary** + +Run: +```bash +git -C /home/jn/projects/codex/codex-skill-library/.worktrees/continuity-install-ux status --short +git -C /home/jn/projects/codex/codex-skill-library/.worktrees/continuity-install-ux diff --stat +``` +Expected: only the planned doc and test files are changed + +- [ ] **Step 6: Commit the final verified state** + +```bash +git add docs/superpowers/plans/2026-03-25-continuity-install-ux.md +git commit -m "docs: record continuity install ux plan" +``` diff --git a/skills/skill-task-continuity/README.md b/skills/skill-task-continuity/README.md index 29b7fe2..16c8982 100644 --- a/skills/skill-task-continuity/README.md +++ b/skills/skill-task-continuity/README.md @@ -33,12 +33,33 @@ It does not replace the atomic skills. ## Install -To install `skill-task-continuity`, use the standard published package path in this repository and choose the release or ref that fits your workflow. +Choose one of these install paths: + +- install only `skill-task-continuity` when you want the suite entry docs and downstream bootstrap helper first +- install the full suite in one command when you want all four continuity packages available immediately + +Installing `skill-task-continuity` does not auto-install the three atomic packages. +Use the full-suite install command when you want all four packages together without running four separate installer commands. You can ask Codex in natural language: - `Use skill-installer to install skill-task-continuity from Golden-Promise/codex-skill-library at skills/skill-task-continuity.` - `Use skill-installer to install skill-task-continuity from Golden-Promise/codex-skill-library at skills/skill-task-continuity using ref v0.6.1.` +- `Use skill-installer to install the full long-task continuity suite from Golden-Promise/codex-skill-library at skills/skill-context-keeper, skills/skill-phase-gate, skills/skill-handoff-summary, and skills/skill-task-continuity.` + +If you want the direct command for the full suite, install all four packages in one command: + +```bash +python3 /scripts/install-skill-from-github.py \ + --repo Golden-Promise/codex-skill-library \ + --path \ + skills/skill-context-keeper \ + skills/skill-phase-gate \ + skills/skill-handoff-summary \ + skills/skill-task-continuity +``` + +Add `--ref v0.6.1` when you want to pin the current published release. For downstream bootstrap walkthroughs and prompt wording, see [references/install-playbook.md](references/install-playbook.md). @@ -65,7 +86,12 @@ Start with one of these three paths: 3. Add thin repo-local wrappers only when a downstream repository truly needs them. The bootstrap helper requires an explicit target and refuses to bootstrap inside this public skill library checkout. -Use `python3 skills/skill-task-continuity/scripts/bootstrap_suite.py --target /path/to/downstream-repo --dry-run` to preview changes, then rerun without `--dry-run` to apply them. + +If you want Codex to handle bootstrap in natural language, say: + +- `Use skill-task-continuity to bootstrap the long-task continuity starter files into /path/to/downstream-repo. Preview the file operations first, then apply them if the preview looks correct. Do not overwrite existing files unless I explicitly ask.` + +If you want exact CLI control instead, use `python3 skills/skill-task-continuity/scripts/bootstrap_suite.py --target /path/to/downstream-repo --dry-run` to preview changes, then rerun without `--dry-run` to apply them. ## How The Suite Composes diff --git a/skills/skill-task-continuity/README.zh-CN.md b/skills/skill-task-continuity/README.zh-CN.md index 02e4c00..463e239 100644 --- a/skills/skill-task-continuity/README.zh-CN.md +++ b/skills/skill-task-continuity/README.zh-CN.md @@ -33,12 +33,33 @@ ## 安装 -安装 `skill-task-continuity` 时，请使用本仓库中的标准发布路径，并按你的工作流选择 release 或 ref。 +安装时可以走下面两条路径之一： + +- 只安装 `skill-task-continuity`，适合先获得套件入口说明和下游 bootstrap 能力 +- 用一条命令安装整套工具链，适合一开始就把 4 个连续性包全部装好 + +安装 `skill-task-continuity` 本身不会自动把另外三个原子包一起装上。 +如果你想一次拿到 4 个包，应该显式使用“整套安装”的命令，而不是分别跑 4 次安装器。 你也可以直接这样对 Codex 说： - `请用 skill-installer 从 Golden-Promise/codex-skill-library 的 skills/skill-task-continuity 安装 skill-task-continuity。` - `请用 skill-installer 从 Golden-Promise/codex-skill-library 的 skills/skill-task-continuity 安装 skill-task-continuity，并使用 ref v0.6.1。` +- `请用 skill-installer 从 Golden-Promise/codex-skill-library 一次安装整套长任务连续性工具链，包括 skills/skill-context-keeper、skills/skill-phase-gate、skills/skill-handoff-summary 和 skills/skill-task-continuity。` + +如果你想直接执行命令，可以用一条命令安装整套工具链： + +```bash +python3 /scripts/install-skill-from-github.py \ + --repo Golden-Promise/codex-skill-library \ + --path \ + skills/skill-context-keeper \ + skills/skill-phase-gate \ + skills/skill-handoff-summary \ + skills/skill-task-continuity +``` + +如果你要固定到当前发布版本，再补上 `--ref v0.6.1` 即可。 关于下游启动流程和提示词措辞，可查看 [references/install-playbook.zh-CN.md](references/install-playbook.zh-CN.md)。 @@ -65,7 +86,12 @@ AGENTS.md 3. 只有在下游仓库确实需要时，才补充轻量的 repo-local wrapper。 启动脚本要求显式传入目标路径，并且会拒绝在这个公共技能库工作区内执行。 -你可以先运行 `python3 skills/skill-task-continuity/scripts/bootstrap_suite.py --target /path/to/downstream-repo --dry-run` 预览变更，再去掉 `--dry-run` 正式应用。 + +如果你想直接用自然语言让 Codex 帮你完成初始化，可以这样说： + +- `请用 skill-task-continuity 把长任务连续性启动文件引导到 /path/to/downstream-repo。先预览文件操作，确认无误后再正式写入；除非我明确要求，否则不要覆盖已有文件。` + +如果你想自己精确执行命令，则可以先运行 `python3 skills/skill-task-continuity/scripts/bootstrap_suite.py --target /path/to/downstream-repo --dry-run` 预览变更，再去掉 `--dry-run` 正式应用。 ## 套件如何组合 diff --git a/skills/skill-task-continuity/references/composition-guide.md b/skills/skill-task-continuity/references/composition-guide.md index 6a8e611..d7a69ad 100644 --- a/skills/skill-task-continuity/references/composition-guide.md +++ b/skills/skill-task-continuity/references/composition-guide.md @@ -10,6 +10,15 @@ Use it to explain how the pieces fit together and to bootstrap downstream files, - `skill-handoff-summary` writes the continuation-oriented handoff when work pauses or changes owners. The suite package exists so a downstream repository can install one entry point, learn the system from one place, and copy starter files into its own repo. +If the team wants all four packages available immediately, the suite can also be installed together with the three atomic packages in one `skill-installer` command. + +## Install Choices + +- install `skill-task-continuity` only when you want the suite entry point first +- install the full suite in one command when you want all four packages available right away + +The suite package stays explicit: it does not auto-install the atomic skills for you. +Instead, it documents the existing multi-path `skill-installer` flow so users can choose one command without hidden side effects. ## Explicit Invocation Wording diff --git a/skills/skill-task-continuity/references/composition-guide.zh-CN.md b/skills/skill-task-continuity/references/composition-guide.zh-CN.md index ead2b8b..cc4f4f8 100644 --- a/skills/skill-task-continuity/references/composition-guide.zh-CN.md +++ b/skills/skill-task-continuity/references/composition-guide.zh-CN.md @@ -10,6 +10,15 @@ - `skill-handoff-summary` 负责在暂停或交接时写出面向续做的交接摘要。 这个组合包的价值在于：下游仓库可以从一个入口安装、从一个入口学习套件结构，并把启动模板复制到自己的仓库里。 +如果团队希望一开始就把 4 个包都装好，也可以用一条 `skill-installer` 命令把组合包和三个原子包一起安装。 + +## 安装选择 + +- 只安装 `skill-task-continuity`，适合先从套件入口理解整体结构 +- 用一条命令安装整套工具链，适合一开始就把 4 个包全部装好 + +这个组合包本身不会隐式自动安装另外三个原子包。 +它做的是把现有的多路径 `skill-installer` 用法文档化，让用户既能一条命令装完整套件，又不会遇到隐藏副作用。 ## 每个原子技能的明确调用措辞 diff --git a/skills/skill-task-continuity/references/install-playbook.md b/skills/skill-task-continuity/references/install-playbook.md index 80a486d..6536966 100644 --- a/skills/skill-task-continuity/references/install-playbook.md +++ b/skills/skill-task-continuity/references/install-playbook.md @@ -18,21 +18,47 @@ The bootstrap helper copies these templates into the downstream repo: ## Bootstrap Walkthrough -1. Install or vendor this package into your tooling environment. +1. Install either: + - just `skill-task-continuity` if you only need the suite entry point first + - the full long-task continuity suite if you want all four packages available immediately 2. Pick the downstream repository root you want to prepare. -3. Preview the file operations: +3. Ask Codex directly when you want a natural-language bootstrap flow: + +```text +Use skill-task-continuity to bootstrap the long-task continuity starter files into /path/to/downstream-repo. +Preview the file operations first, then apply them if the preview looks correct. +Do not overwrite existing files unless I explicitly ask. +``` + +4. If you want exact CLI control, preview the file operations: ```bash python3 skills/skill-task-continuity/scripts/bootstrap_suite.py --target /path/to/downstream-repo --dry-run ``` -4. Run the real bootstrap when the preview looks correct: +5. Run the real bootstrap when the preview looks correct: ```bash python3 skills/skill-task-continuity/scripts/bootstrap_suite.py --target /path/to/downstream-repo ``` -5. Re-run with `--force` only when you intentionally want to overwrite an existing downstream file. +6. Re-run with `--force` only when you intentionally want to overwrite an existing downstream file. + +## Full-Suite Install In One Command + +If you want all four continuity packages in one command, use the existing multi-path support in `skill-installer`: + +```bash +python3 /scripts/install-skill-from-github.py \ + --repo Golden-Promise/codex-skill-library \ + --path \ + skills/skill-context-keeper \ + skills/skill-phase-gate \ + skills/skill-handoff-summary \ + skills/skill-task-continuity +``` + +Add `--ref v0.6.1` when you want the pinned release. ## Expected Downstream Layout diff --git a/skills/skill-task-continuity/references/install-playbook.zh-CN.md b/skills/skill-task-continuity/references/install-playbook.zh-CN.md index fe5bd3c..1fde2d1 100644 --- a/skills/skill-task-continuity/references/install-playbook.zh-CN.md +++ b/skills/skill-task-continuity/references/install-playbook.zh-CN.md @@ -18,21 +18,47 @@ ## 启动流程 -1. 先在你的工具环境中安装或引入这个组合包。 +1. 先决定安装方式： + - 只安装 `skill-task-continuity`，先拿到套件入口和 bootstrap 能力 + - 一次安装整套连续性工具链，直接把 4 个包都装好 2. 选定需要初始化的下游仓库根目录。 -3. 先用 dry run 预览文件操作： +3. 如果你希望通过自然语言让 Codex 帮你完成初始化，可以直接这样对 Codex 说： + +```text +请用 skill-task-continuity 把长任务连续性启动文件引导到 /path/to/downstream-repo。 +先预览文件操作，确认无误后再正式写入。 +除非我明确要求，否则不要覆盖已有文件。 +``` + +4. 如果你想自己精确控制命令，再先用 dry run 预览文件操作： ```bash python3 skills/skill-task-continuity/scripts/bootstrap_suite.py --target /path/to/downstream-repo --dry-run ``` -4. 确认预览结果正确后，再执行真正的启动： +5. 确认预览结果正确后，再执行真正的启动： ```bash python3 skills/skill-task-continuity/scripts/bootstrap_suite.py --target /path/to/downstream-repo ``` -5. 只有在你明确要覆盖已有下游文件时，才加上 `--force`。 +6. 只有在你明确要覆盖已有下游文件时，才加上 `--force`。 + +## 一条命令安装整套工具链 + +如果你想把 4 个连续性包一次装好，可以直接利用 `skill-installer` 现有的多路径能力： + +```bash +python3 /scripts/install-skill-from-github.py \ + --repo Golden-Promise/codex-skill-library \ + --path \ + skills/skill-context-keeper \ + skills/skill-phase-gate \ + skills/skill-handoff-summary \ + skills/skill-task-continuity +``` + +如果你需要固定到当前发布版本，再补上 `--ref v0.6.1`。 ## 期望的下游布局 diff --git a/skills/skill-task-continuity/tests/test_docs_contract.py b/skills/skill-task-continuity/tests/test_docs_contract.py new file mode 100644 index 0000000..08a449f --- /dev/null +++ b/skills/skill-task-continuity/tests/test_docs_contract.py @@ -0,0 +1,57 @@ +from pathlib import Path +import unittest + + +ROOT = Path(__file__).resolve().parents[1] + + +class SkillTaskContinuityDocsContractTests(unittest.TestCase): + def test_english_readme_mentions_full_suite_install(self): + text = (ROOT / "README.md").read_text(encoding="utf-8") + lowered = text.lower() + + self.assertIn("install the full suite", lowered) + self.assertIn("one command", lowered) + for skill_path in [ + "skills/skill-context-keeper", + "skills/skill-phase-gate", + "skills/skill-handoff-summary", + "skills/skill-task-continuity", + ]: + self.assertIn(skill_path, text) + + def test_chinese_readme_mentions_full_suite_install(self): + text = (ROOT / "README.zh-CN.md").read_text(encoding="utf-8") + + self.assertIn("一条命令", text) + self.assertIn("整套", text) + for skill_path in [ + "skills/skill-context-keeper", + "skills/skill-phase-gate", + "skills/skill-handoff-summary", + "skills/skill-task-continuity", + ]: + self.assertIn(skill_path, text) + + def test_english_install_playbook_prefers_natural_language_bootstrap(self): + text = (ROOT / "references" / "install-playbook.md").read_text(encoding="utf-8") + lowered = text.lower() + + self.assertIn("ask codex", lowered) + self.assertIn("bootstrap", lowered) + self.assertIn("--dry-run", text) + self.assertIn("--force", text) + + def test_chinese_install_playbook_prefers_natural_language_bootstrap(self): + text = (ROOT / "references" / "install-playbook.zh-CN.md").read_text( + encoding="utf-8" + ) + + self.assertIn("直接这样对 Codex 说", text) + self.assertIn("启动", text) + self.assertIn("--dry-run", text) + self.assertIn("--force", text) + + +if __name__ == "__main__": + unittest.main() From 25c8e1f5ae0fa4b1ebe412b50405d64c57b24454 Mon Sep 17 00:00:00 2001 From: NuoJin <1430093320@qq.com> Date: Wed, 25 Mar 2026 21:13:06 +0800 Subject: [PATCH 2/2] docs: clarify continuity skill invocation wording --- skills/skill-context-keeper/README.md | 7 +++++++ skills/skill-context-keeper/README.zh-CN.md | 7 +++++++ .../skill-context-keeper/tests/test_package_contract.py | 5 +++++ skills/skill-handoff-summary/README.md | 7 +++++++ skills/skill-handoff-summary/README.zh-CN.md | 7 +++++++ .../skill-handoff-summary/tests/test_package_contract.py | 8 ++++++++ skills/skill-phase-gate/README.md | 7 +++++++ skills/skill-phase-gate/README.zh-CN.md | 7 +++++++ skills/skill-phase-gate/tests/test_package_contract.py | 5 +++++ 9 files changed, 60 insertions(+) diff --git a/skills/skill-context-keeper/README.md b/skills/skill-context-keeper/README.md index cedb355..47e7d4e 100644 --- a/skills/skill-context-keeper/README.md +++ b/skills/skill-context-keeper/README.md @@ -59,6 +59,13 @@ Start with one of these three paths: If you want ready-to-paste prompts, see [references/prompt-templates.en.md](references/prompt-templates.en.md). +## Direct Codex Usage + +If you want to tell Codex exactly what to do, say: + +- `Use skill-context-keeper to refresh the current task state from the repository before we continue.` +- `Use skill-context-keeper to rebuild the last known task state and rewrite .agent-state/TASK_STATE.md.` + ## Documentation - Trigger routing and package boundary: `SKILL.md` diff --git a/skills/skill-context-keeper/README.zh-CN.md b/skills/skill-context-keeper/README.zh-CN.md index e73100d..59f5242 100644 --- a/skills/skill-context-keeper/README.zh-CN.md +++ b/skills/skill-context-keeper/README.zh-CN.md @@ -53,6 +53,13 @@ 如果你想直接套用提示词模板，请查看 [references/prompt-templates.zh-CN.md](references/prompt-templates.zh-CN.md)。 +## 直接告诉 Codex 怎么做 + +如果你想直接用自然语言告诉 Codex，可以这样说： + +- `请用 skill-context-keeper 根据仓库现状刷新当前任务状态。` +- `请用 skill-context-keeper 重建最近一次可信任务状态，并重写 .agent-state/TASK_STATE.md。` + ## 文档 - 触发路由与包边界：`SKILL.md` diff --git a/skills/skill-context-keeper/tests/test_package_contract.py b/skills/skill-context-keeper/tests/test_package_contract.py index c0b4bb2..4c1bd11 100644 --- a/skills/skill-context-keeper/tests/test_package_contract.py +++ b/skills/skill-context-keeper/tests/test_package_contract.py @@ -48,6 +48,11 @@ def test_readme_spells_out_package_boundary(self): self.assertIn("does not own workflow gating", text) self.assertIn("does not own final handoffs", text) + def test_readme_includes_direct_natural_language_usage(self): + text = (ROOT / "README.md").read_text(encoding="utf-8").lower() + self.assertIn("if you want to tell codex exactly what to do", text) + self.assertIn("use skill-context-keeper to refresh the current task state", text) + def test_reference_indexes_point_to_published_files(self): english = (ROOT / "references" / "README.md").read_text(encoding="utf-8") chinese = (ROOT / "references" / "README.zh-CN.md").read_text(encoding="utf-8") diff --git a/skills/skill-handoff-summary/README.md b/skills/skill-handoff-summary/README.md index 7ff2a9b..5512790 100644 --- a/skills/skill-handoff-summary/README.md +++ b/skills/skill-handoff-summary/README.md @@ -56,6 +56,13 @@ Start with one of these three paths: If you want ready-to-paste prompts, see [references/prompt-templates.en.md](references/prompt-templates.en.md). +## Direct Codex Usage + +If you want to tell Codex exactly what to do, say: + +- `Use skill-handoff-summary to write a compact continuation-oriented handoff before we pause.` +- `Use skill-handoff-summary to write .agent-state/HANDOFF.md with the exact next action and a reusable resume prompt.` + ## Documentation - Trigger routing and package boundary: `SKILL.md` diff --git a/skills/skill-handoff-summary/README.zh-CN.md b/skills/skill-handoff-summary/README.zh-CN.md index 442264e..fd6f767 100644 --- a/skills/skill-handoff-summary/README.zh-CN.md +++ b/skills/skill-handoff-summary/README.zh-CN.md @@ -55,6 +55,13 @@ 如果你想直接套用提示词模板，请查看 [references/prompt-templates.zh-CN.md](references/prompt-templates.zh-CN.md)。 +## 直接告诉 Codex 怎么做 + +如果你想直接用自然语言告诉 Codex，可以这样说： + +- `请用 skill-handoff-summary 在暂停前写一个紧凑、面向续做的交接摘要。` +- `请用 skill-handoff-summary 把交接写到 .agent-state/HANDOFF.md，并附上下一次会话可复用的 resume prompt。` + ## 文档 - 触发路由与包边界：`SKILL.md` diff --git a/skills/skill-handoff-summary/tests/test_package_contract.py b/skills/skill-handoff-summary/tests/test_package_contract.py index 73910a4..637e36b 100644 --- a/skills/skill-handoff-summary/tests/test_package_contract.py +++ b/skills/skill-handoff-summary/tests/test_package_contract.py @@ -43,6 +43,14 @@ def test_readme_describes_continuation_boundary(self): self.assertIn("not whole-project documentation", text) self.assertIn(".agent-state/handoff.md", text) + def test_readme_includes_direct_natural_language_usage(self): + text = (ROOT / "README.md").read_text(encoding="utf-8").lower() + self.assertIn("if you want to tell codex exactly what to do", text) + self.assertIn( + "use skill-handoff-summary to write a compact continuation-oriented handoff", + text, + ) + def test_bilingual_references_include_positive_and_negative_examples(self): english = (ROOT / "references" / "use-cases.md").read_text(encoding="utf-8") chinese = (ROOT / "references" / "use-cases.zh-CN.md").read_text(encoding="utf-8") diff --git a/skills/skill-phase-gate/README.md b/skills/skill-phase-gate/README.md index c701666..55bed1d 100644 --- a/skills/skill-phase-gate/README.md +++ b/skills/skill-phase-gate/README.md @@ -63,6 +63,13 @@ Start with one of these three paths: If you want ready-to-paste prompts, see [references/prompt-templates.en.md](references/prompt-templates.en.md). +## Direct Codex Usage + +If you want to tell Codex exactly what to do, say: + +- `Use skill-phase-gate to create a preflight gate before this risky multi-file change.` +- `Use skill-phase-gate to create a postflight gate for this meaningful edit before I commit.` + ## Documentation - Trigger routing and package boundary: `SKILL.md` diff --git a/skills/skill-phase-gate/README.zh-CN.md b/skills/skill-phase-gate/README.zh-CN.md index bca7929..caa415b 100644 --- a/skills/skill-phase-gate/README.zh-CN.md +++ b/skills/skill-phase-gate/README.zh-CN.md @@ -63,6 +63,13 @@ 如果你想直接套用提示词模板，请查看 [references/prompt-templates.zh-CN.md](references/prompt-templates.zh-CN.md)。 +## 直接告诉 Codex 怎么做 + +如果你想直接用自然语言告诉 Codex，可以这样说： + +- `请用 skill-phase-gate 在这次高风险多文件修改前生成一个 preflight gate。` +- `请用 skill-phase-gate 在我提交前为这次有分量的改动生成一个 postflight gate。` + ## 文档 - 触发路由与包边界：`SKILL.md` diff --git a/skills/skill-phase-gate/tests/test_package_contract.py b/skills/skill-phase-gate/tests/test_package_contract.py index 757fd1f..af4f006 100644 --- a/skills/skill-phase-gate/tests/test_package_contract.py +++ b/skills/skill-phase-gate/tests/test_package_contract.py @@ -49,6 +49,11 @@ def test_readme_rules_out_trivial_or_explanation_only_usage(self): self.assertIn("not for trivial one-line edits", text) self.assertIn("not for pure explanation tasks", text) + def test_readme_includes_direct_natural_language_usage(self): + text = (ROOT / "README.md").read_text(encoding="utf-8").lower() + self.assertIn("if you want to tell codex exactly what to do", text) + self.assertIn("use skill-phase-gate to create a preflight gate", text) + if __name__ == "__main__": unittest.main()