Golden-Promise · Golden-Promise · Mar 25, 2026 · Mar 25, 2026
diff --git a/docs/superpowers/plans/2026-03-25-continuity-readme-entry-polish.md b/docs/superpowers/plans/2026-03-25-continuity-readme-entry-polish.md
@@ -0,0 +1,117 @@
+# Continuity README Entry Polish 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 docs feel friendlier and faster for first-time users while preserving package boundaries and bilingual alignment.
+
+**Architecture:** Rework the `skills/` index into a true decision entry page, then reshape the four continuity package READMEs into landing pages that lead with use cases, outputs, and natural-language Codex prompts. Keep shell commands available, but push them below the first-screen newcomer path.
+
+**Tech Stack:** Markdown docs, Python `unittest` contract tests
+
+---
+
+### Task 1: Lock the New Entry-Page Contract
+
+**Files:**
+- 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`
+- Modify: `skills/skill-task-continuity/tests/test_docs_contract.py`
+
+- [ ] **Step 1: Add failing assertions for the new README entry structure**
+
+Add tests that require:
+- a quick-pick continuity block in `skills/README.md` and `skills/README.zh-CN.md`
+- newcomer-first headings in the four README files
+- natural-language install wording near the top
+- explicit “what file gets created or updated” wording
+
+- [ ] **Step 2: Run the targeted docs-contract tests and verify they fail**
+
+Run: `python3 -m unittest 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 skills/skill-task-continuity/tests/test_docs_contract.py -v`
+Expected: FAIL because the current README files still use the older structure.
+
+### Task 2: Rewrite the Skills Index as a True Entry Page
+
+**Files:**
+- Modify: `skills/README.md`
+- Modify: `skills/README.zh-CN.md`
+
+- [ ] **Step 1: Add a quick continuity decision block near the top**
+
+Write a short “pick the right continuity skill” guide that maps:
+- stale task state -> `skill-context-keeper`
+- risky or multi-file change -> `skill-phase-gate`
+- pause or handoff -> `skill-handoff-summary`
+- first-time suite setup -> `skill-task-continuity`
+
+- [ ] **Step 2: Keep the package table, but demote it to second-level detail**
+
+Retain the published package table and package conventions, but make the fast decision guide the first thing new users read.
+
+### Task 3: Reshape the Three Atomic README Pages
+
+**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`
+
+- [ ] **Step 1: Move each README to a faster landing-page flow**
+
+Use a newcomer-friendly order that leads with:
+- when to use the package
+- what the user will get
+- what file or artifact usually changes
+- what to say to Codex first
+- related skills
+
+Keep “don’t use this when” and boundary wording, but move it below the first-screen orientation.
+
+- [ ] **Step 2: Keep install guidance natural-language first**
+
+Show the natural-language install prompt in the main install section.
+Keep the exact shell install command available, but lower on the page so first-time users can start without hunting for script paths.
+
+### Task 4: Reposition `skill-task-continuity` as the Beginner Entry Package
+
+**Files:**
+- Modify: `skills/skill-task-continuity/README.md`
+- Modify: `skills/skill-task-continuity/README.zh-CN.md`
+
+- [ ] **Step 1: Rewrite the opening as a first-time setup page**
+
+Lead with language like:
+- start here for first-time setup
+- what gets created in the repo
+- fastest setup
+- which skill to use next
+
+Move terms such as atomic package boundaries or maintainer-style design notes lower on the page.
+
+- [ ] **Step 2: Keep full-suite install easy without implying hidden auto-install**
+
+Preserve the explicit one-command full-suite install path and the statement that `skill-task-continuity` does not auto-install the atomic packages.
+Lead with natural-language prompts first, and keep the exact CLI command available later.
+
+### Task 5: Verify the New Entry Experience
+
+**Files:**
+- Verify: `skills/README.md`
+- Verify: `skills/README.zh-CN.md`
+- Verify: the four package README files
+
+- [ ] **Step 1: Re-run the targeted docs-contract tests**
+
+Run: `python3 -m unittest 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 skills/skill-task-continuity/tests/test_docs_contract.py -v`
+Expected: PASS
+
+- [ ] **Step 2: Re-read the edited README files for tone and symmetry**
+
+Check that:
+- English and Chinese pages stay aligned
+- first-screen wording is user-friendly
+- commands are no longer the first thing a newcomer sees
+- package boundaries still remain clear
diff --git a/skills/README.md b/skills/README.md
@@ -4,11 +4,25 @@
 
 This directory contains the installable skill packages published by `codex-skill-library`.
 
+## Pick the Right Continuity Skill
+
+Use this quick guide first:
+
+- I paused a task and need to rebuild the current picture.
+  Start with `skill-context-keeper`.
+- I am about to make a risky or multi-file change.
+  Start with `skill-phase-gate`.
+- I need to stop now and leave a durable restart note.
+  Start with `skill-handoff-summary`.
+- I want to set up the whole continuity workflow in a repo for the first time.
+  Start with `skill-task-continuity`.
+
 ## How To Use This Index
 
-1. Scan the table below to find the skill that matches your task.
-2. Open the package README in your preferred language.
-3. Use the package reference pages for boundary notes now, and later for examples or prompt wording.
+1. Start with the quick picker above if you are working on continuity setup or continuity workflow tasks.
+2. Scan the table below to find the package that matches your next action.
+3. Open the package README in your preferred language.
+4. Use the package reference pages for examples, prompt wording, and deeper boundary notes when needed.
 
 ## Published Packages
 

diff --git a/skills/README.zh-CN.md b/skills/README.zh-CN.md
@@ -4,11 +4,25 @@
 
 这个目录存放 `codex-skill-library` 中可安装、可发布的 skill 包。
 
+## 选择合适的连续性技能
+
+先看这份快速指南：
+
+- 我暂停了一个任务，现在需要重新拼出当前图景。
+  先用 `skill-context-keeper`。
+- 我马上要做一个高风险或多文件改动。
+  先用 `skill-phase-gate`。
+- 我现在要停下来，并留下一个可以直接续做的重启说明。
+  先用 `skill-handoff-summary`。
+- 我第一次想在仓库里装好整套连续性工作流。
+  先用 `skill-task-continuity`。
+
 ## 如何使用这个索引页
 
-1. 先看下面的表格，找到与你任务最匹配的 skill。
-2. 打开该包对应语言的 README。
-3. 现在先看包内参考页了解边界说明，后续阶段再继续使用其中补充的示例、提示词或更细说明。
+1. 如果你处理的是连续性工作流或连续性搭建问题，先看上面的快速选型块。
+2. 再看下面的表格，找到与你下一步动作最匹配的包。
+3. 打开该包对应语言的 README。
+4. 当你需要示例、提示词或更细的边界说明时，再去看包里的 `references/` 页面。
 
 ## 已发布包
 

diff --git a/skills/skill-context-keeper/README.md b/skills/skill-context-keeper/README.md
@@ -4,67 +4,56 @@
 
 ## Overview
 
-`skill-context-keeper` is the focused package for recovering and refreshing structured task state during long-running coding work.
-It helps the next turn start from the best verified picture of the task without expanding into checkpoints, workflow control, or final handoff writing.
+`skill-context-keeper` is the focused package for refreshing structured task state during long-running coding work.
+Use it when the task is still ongoing, but the working context is stale.
 
-## Core Capabilities
+## Start Here In 30 Seconds
 
-`skill-context-keeper` is designed for one job: keeping ongoing task state trustworthy and resumable.
+- Use this when: the task is still active, but the current picture is stale, scattered, or partially trusted.
+- You'll get: a compact, verified task snapshot that separates facts, assumptions, decisions, risks, and next actions.
+- Typical output: updates `.agent-state/TASK_STATE.md`.
 
-- rebuild the current task picture from verified repository facts
-- keep facts, assumptions, decisions, risks, and next actions clearly separated
-- refresh compact downstream state files such as `.agent-state/TASK_STATE.md`
-- preserve just enough continuity for the next turn without turning into a full workflow package
+If you want to tell Codex exactly what to do:
 
-Use this skill when the main problem is stale or scattered task context rather than workflow control.
+Try this first:
 
-## Best For
-
-- resuming a paused task after the working context has drifted
-- resuming a task after an interruption or stale summary
-- rebuilding the current state before making more code changes
-- rebuilding the last known task state before new work continues
-- refreshing open TODOs, assumptions, and recent changes in one place
-- reconciling what the thread believes with what the repository now shows
-
-If you are picking an entry point, start here when the main problem is stale or scattered task context.
-
-## What It Is Not For
-
-- breaking a task into staged execution phases
-- deciding checkpoint rules or phase exit criteria
-- writing a final pause or transfer handoff for another agent
-- bootstrapping the full long-task continuity suite
-
-This package does not own workflow gating and does not own final handoffs.
+- `Use skill-context-keeper to refresh the current task state from the repository before we continue.`
 
 ## Install
 
-To install `skill-context-keeper`, use the standard published package path in this repository and choose the release or ref that fits your workflow.
-
 You can ask Codex in natural language:
 
 - `Use skill-installer to install skill-context-keeper from Golden-Promise/codex-skill-library at skills/skill-context-keeper.`
 - `Use skill-installer to install skill-context-keeper from Golden-Promise/codex-skill-library at skills/skill-context-keeper using ref v0.6.1.`
 
-For trigger examples and prompt wording, see [references/use-cases.md](references/use-cases.md).
+If you want the exact shell command, jump to [Install Details](#install-details).
 
-## Common Paths
+## What File Will This Create Or Update?
 
-Start with one of these three paths:
+The typical downstream file is `.agent-state/TASK_STATE.md`.
 
-1. Resume a paused task after the working picture has drifted.
-2. Refresh task state before more implementation work.
-3. Reconcile facts, open issues, and the next action in `.agent-state/TASK_STATE.md`.
+Use this package when you want to refresh or rewrite that task-state file so the next turn can resume from a trusted summary of:
 
-If you want ready-to-paste prompts, see [references/prompt-templates.en.md](references/prompt-templates.en.md).
+- the current objective
+- current repository facts
+- completed work
+- open issues and risks
+- the next recommended action
 
-## Direct Codex Usage
+## Don't Use This When
 
-If you want to tell Codex exactly what to do, say:
+- you need a preflight or postflight checkpoint around a risky change
+- you need a durable pause or transfer handoff
+- you are setting up the full continuity workflow in a repo for the first time
+- you want generic workflow control instead of state refresh
 
-- `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.`
+This package does not own workflow gating and does not own final handoffs.
+
+## Related Skills
+
+- `skill-phase-gate` for meaningful preflight and postflight checkpoints
+- `skill-handoff-summary` for pause and transfer notes
+- `skill-task-continuity` for first-time continuity setup and suite-level guidance
 
 ## Documentation
 
@@ -74,3 +63,14 @@ If you want to tell Codex exactly what to do, say:
 - Prompt templates: [references/prompt-templates.en.md](references/prompt-templates.en.md)
 - Chinese prompt templates: [references/prompt-templates.zh-CN.md](references/prompt-templates.zh-CN.md)
 - Task-state template: [assets/TASK_STATE.template.md](assets/TASK_STATE.template.md)
+
+## Install Details
+
+Replace `/path/to/install-skill-from-github.py` with the actual path to your local `skill-installer` checkout.
+
+```bash
+python3 /path/to/install-skill-from-github.py \
+  --repo Golden-Promise/codex-skill-library \
+  --path skills/skill-context-keeper \
+  --ref v0.6.1
+```
diff --git a/skills/skill-context-keeper/README.zh-CN.md b/skills/skill-context-keeper/README.zh-CN.md
@@ -4,61 +4,56 @@
 
 ## 概述
 
-`skill-context-keeper` 是一个专注型包，专门用于在长时间编码任务中恢复和刷新结构化任务状态。
-它帮助下一轮从当前最可信、已验证的任务图景继续，而不会扩展成检查点、流程控制或最终交接说明。
+`skill-context-keeper` 是一个专注型包，用于在长时间编码任务中刷新结构化任务状态。
+当任务还没结束，但你手上的任务图景已经变旧、变散或不再完全可信时，就该用它。
 
-## 核心能力
+## 30 秒快速开始
 
-`skill-context-keeper` 只聚焦一件事：让进行中的任务状态保持可信、可续做。
+- 什么时候用：任务仍在继续，但当前上下文已经陈旧、分散，或者可信度不够。
+- 你会得到什么：一个紧凑、可信的任务快照，把事实、假设、决策、风险和下一步动作分清楚。
+- 典型产物：更新 `.agent-state/TASK_STATE.md`。
 
-- 根据已验证的仓库事实重建当前任务图景
-- 清楚区分事实、假设、决策、风险和下一步动作
-- 刷新诸如 `.agent-state/TASK_STATE.md` 的紧凑下游状态文件
-- 只保留下一轮继续执行所需的连续性，不膨胀成整套工作流包
+如果你想直接告诉 Codex 怎么做：
 
-## 适用场景
+先这样对 Codex 说：
 
-- 任务暂停后重新进入，且上下文已经开始漂移
-- 在继续改代码前先重建当前任务状态
-- 用一个稳定入口刷新待办、假设和最近变更
-- 对齐线程认知与仓库现状，避免带着旧前提继续推进
-
-如果你在几个连续性包之间做选择，而当前主要问题是“任务状态过时或散落”，优先从这个包开始。
-
-## 不适用场景
-
-- 把任务拆成分阶段执行
-- 决定检查点规则或阶段退出条件
-- 为另一个执行者撰写暂停或转交说明
-- 启动整套长任务连续性套件
+- `请用 skill-context-keeper 根据仓库现状刷新当前任务状态。`
 
 ## 安装
 
-安装 `skill-context-keeper` 时，请使用本仓库中的标准发布路径，并按你的工作流选择 release 或 ref。
-
-你也可以直接这样对 Codex 说：
+你可以直接这样对 Codex 说：
 
 - `请用 skill-installer 从 Golden-Promise/codex-skill-library 的 skills/skill-context-keeper 安装 skill-context-keeper。`
 - `请用 skill-installer 从 Golden-Promise/codex-skill-library 的 skills/skill-context-keeper 安装 skill-context-keeper，并使用 ref v0.6.1。`
 
-关于触发示例和提示词措辞，可查看 [references/use-cases.zh-CN.md](references/use-cases.zh-CN.md)。
+如果你想看精确的 shell 命令，可以直接跳到后面的 [安装细节](#安装细节)。
 
-## 常用路径
+## 会创建或更新什么文件？
 
-可以先从下面三条路径开始：
+最典型的下游文件是 `.agent-state/TASK_STATE.md`。
 
-1. 在任务暂停一段时间后恢复上下文。
-2. 在继续实现前刷新当前任务状态。
-3. 把事实、未决问题和下一步动作收敛到 `.agent-state/TASK_STATE.md`。
+当你希望刷新或重写这个任务状态文件，让下一轮可以从一个可信摘要继续时，就该用这个包。它通常会帮助你整理：
 
-如果你想直接套用提示词模板，请查看 [references/prompt-templates.zh-CN.md](references/prompt-templates.zh-CN.md)。
+- 当前目标
+- 仓库里的已验证事实
+- 已完成工作
+- 开放问题和风险
+- 下一步推荐动作
 
-## 直接告诉 Codex 怎么做
+## 不适合什么时候用
 
-如果你想直接用自然语言告诉 Codex，可以这样说：
+- 你需要为高风险改动加 preflight 或 postflight 检查点
+- 你需要写一份可交接、可暂停的 handoff
+- 你是第一次在仓库里搭建整套连续性工作流
+- 你想要的是泛化的流程控制，而不是状态刷新
 
-- `请用 skill-context-keeper 根据仓库现状刷新当前任务状态。`
-- `请用 skill-context-keeper 重建最近一次可信任务状态，并重写 .agent-state/TASK_STATE.md。`
+这个包不负责 workflow gating，也不负责 final handoffs。
+
+## 相关技能
+
+- `skill-phase-gate`：适合高价值的 preflight / postflight 检查点
+- `skill-handoff-summary`：适合暂停或转交时写 handoff
+- `skill-task-continuity`：适合第一次搭建整套连续性流程
 
 ## 文档
 
@@ -68,3 +63,14 @@
 - 中文提示词模板：[references/prompt-templates.zh-CN.md](references/prompt-templates.zh-CN.md)
 - English prompt templates: [references/prompt-templates.en.md](references/prompt-templates.en.md)
 - 任务状态模板：[assets/TASK_STATE.template.md](assets/TASK_STATE.template.md)
+
+## 安装细节
+
+把 `/path/to/install-skill-from-github.py` 换成你本地 `skill-installer` 仓库里的实际脚本路径。
+
+```bash
+python3 /path/to/install-skill-from-github.py \
+  --repo Golden-Promise/codex-skill-library \
+  --path skills/skill-context-keeper \
+  --ref v0.6.1
+```