diff --git a/CHANGELOG.md b/CHANGELOG.md index 98d9b97..86a9a6d 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -4,22 +4,21 @@ All notable changes to `codex-skill-library` should be documented in this file. ## [Unreleased] +## [0.7.0] - 2026-03-27 + ### Added -- Publish four long-task continuity packages under `skills/`: `skill-context-keeper`, `skill-phase-gate`, `skill-handoff-summary`, and `skill-task-continuity`. -- Add bilingual package entry docs, routing-first `SKILL.md` files, OpenAI agent metadata, reader-facing references, downstream template assets, and package contract tests for the new continuity packages. -- Add the continuity-suite bootstrap helper and downstream template set for `AGENTS.md` plus `.agent-state/*.md` files without turning the repository root into a consumer repo. -- Add `docs/long-task-suite.md` and `docs/long-task-suite.zh-CN.md` so maintainers and readers can understand the suite architecture without opening package internals. -- Add a static continuity eval harness under `evals/` with seed cases, per-package artifact checks, routing checks, exact workflow-token checks, and optional guardrail metadata validation. -- Add a pull-request workflow for published package tests plus continuity eval checks. -- Add bilingual release checklist guidance for the continuity-suite publication flow. +- Publish the context-protocol continuity suite under `skills/`, including the new atomic packages `skill-subtask-context` and `skill-context-packet`. +- Add layered starter assets for `AGENTS.md`, `.agent-state/INDEX.md`, `.agent-state/root/`, `.agent-state/subtasks/`, and archive directories through the continuity bootstrap helper. +- Add bilingual migration guides in [docs/context-protocol-migration.md](docs/context-protocol-migration.md) and [docs/context-protocol-migration.zh-CN.md](docs/context-protocol-migration.zh-CN.md). +- Add protocol-era suite overview docs that describe root state, subtask state, packets, checkpoints, and handoffs as separate continuity objects. +- Expand the static continuity eval harness to cover six packages, root/subtask/packet artifact tokens, and protocol-era workflow cases. ### Changed -- Update root docs, skills indexes, and publishing guides so all four continuity packages are discoverable, install guidance stays aligned with `skill-installer`, and maintainers can find smoke-test and release-checklist steps quickly. -- Move command-heavy install examples out of the repository root README and keep package-level install guidance closer to the published package entry points. -- Polish the four continuity package READMEs so they read more like package landing pages, stay friendlier for first-time readers, and preserve strict package boundaries. -- Keep pinned install guidance aligned to the upcoming `v0.6.1` release after withdrawing the original `v0.6.0` tag. +- Refocus `skill-context-keeper` on root-state refresh and compression, `skill-handoff-summary` on root/subtask handoffs, and `skill-phase-gate` on optional operational checkpoints. +- Update root repository indexes and suite docs so the six-package continuity model is discoverable from the repo landing pages. +- Rewrite publishing and release-checklist docs around protocol validation, six-package smoke tests, and release-scope-driven tag selection instead of a fixed placeholder version. - Treat the continuity eval contract as a release-facing surface: routing now depends on published trigger guidance, workflow tokens must match exact package and polarity contracts, and optional guardrail metadata must be valid when present. ## [0.5.1] - 2026-03-25 diff --git a/README.md b/README.md index 771f5a7..c010886 100644 --- a/README.md +++ b/README.md @@ -26,7 +26,9 @@ This repository is designed for people who want to: | Skill | Best For | Docs | | --- | --- | --- | | `skill-governance` | Governing skill assets with task-first add, enable, doctor, repair, audit, and document flows | [EN](skills/skill-governance/README.md) / [中文](skills/skill-governance/README.zh-CN.md) | -| `skill-context-keeper` | Refreshing current task state without drifting into checkpoints or handoff ownership | [EN](skills/skill-context-keeper/README.md) / [中文](skills/skill-context-keeper/README.zh-CN.md) | +| `skill-context-keeper` | Refreshing and compressing trusted root-task state | [EN](skills/skill-context-keeper/README.md) / [中文](skills/skill-context-keeper/README.zh-CN.md) | +| `skill-subtask-context` | Opening and maintaining bounded child-task state without bloating the root summary | [EN](skills/skill-subtask-context/README.md) / [中文](skills/skill-subtask-context/README.zh-CN.md) | +| `skill-context-packet` | Writing the minimum next-turn context packet for root or subtask work | [EN](skills/skill-context-packet/README.md) / [中文](skills/skill-context-packet/README.zh-CN.md) | | `skill-phase-gate` | Adding preflight and postflight checkpoints around meaningful edits | [EN](skills/skill-phase-gate/README.md) / [中文](skills/skill-phase-gate/README.zh-CN.md) | | `skill-handoff-summary` | Writing compact continuation handoffs when work pauses or changes owners | [EN](skills/skill-handoff-summary/README.md) / [中文](skills/skill-handoff-summary/README.zh-CN.md) | | `skill-task-continuity` | Bootstrapping and composing the continuity suite without replacing the atomic packages | [EN](skills/skill-task-continuity/README.md) / [中文](skills/skill-task-continuity/README.zh-CN.md) | @@ -36,7 +38,7 @@ This repository is designed for people who want to: 1. Open the package list in [skills/README.md](skills/README.md). 2. Choose a skill and read its package `README.md`. 3. Follow the installation guidance in that package README. -4. For the continuity workflow, start with `skill-task-continuity` when you need suite bootstrap or composition guidance, or install the narrower atomic package directly. +4. For the continuity workflow, start with `skill-task-continuity` when you need suite bootstrap or composition guidance, or jump directly to `skill-context-keeper`, `skill-subtask-context`, `skill-context-packet`, `skill-phase-gate`, or `skill-handoff-summary` when the next action is already clear. 5. Use the package reference pages for boundary notes now, and later for examples, prompts, and deeper guidance. ## Reading Guide @@ -45,9 +47,15 @@ This repository is designed for people who want to: - 中文技能索引: [skills/README.zh-CN.md](skills/README.zh-CN.md) - `skill-governance` package: [EN](skills/skill-governance/README.md) / [中文](skills/skill-governance/README.zh-CN.md) - `skill-context-keeper` package: [EN](skills/skill-context-keeper/README.md) / [中文](skills/skill-context-keeper/README.zh-CN.md) +- `skill-subtask-context` package: [EN](skills/skill-subtask-context/README.md) / [中文](skills/skill-subtask-context/README.zh-CN.md) +- `skill-context-packet` package: [EN](skills/skill-context-packet/README.md) / [中文](skills/skill-context-packet/README.zh-CN.md) - `skill-phase-gate` package: [EN](skills/skill-phase-gate/README.md) / [中文](skills/skill-phase-gate/README.zh-CN.md) - `skill-handoff-summary` package: [EN](skills/skill-handoff-summary/README.md) / [中文](skills/skill-handoff-summary/README.zh-CN.md) - `skill-task-continuity` package: [EN](skills/skill-task-continuity/README.md) / [中文](skills/skill-task-continuity/README.zh-CN.md) +- Context protocol migration guide: [docs/context-protocol-migration.md](docs/context-protocol-migration.md) +- 中文迁移说明: [docs/context-protocol-migration.zh-CN.md](docs/context-protocol-migration.zh-CN.md) +- Continuity suite overview: [docs/long-task-suite.md](docs/long-task-suite.md) +- 中文连续性套件总览: [docs/long-task-suite.zh-CN.md](docs/long-task-suite.zh-CN.md) - Repository publishing guide: [docs/publishing.md](docs/publishing.md) - 中文发布说明: [docs/publishing.zh-CN.md](docs/publishing.zh-CN.md) - Release checklist for the continuity suite: [docs/release-checklist-long-task-suite.md](docs/release-checklist-long-task-suite.md) @@ -66,6 +74,8 @@ codex-skill-library/ README.zh-CN.md skill-governance/ skill-context-keeper/ + skill-subtask-context/ + skill-context-packet/ skill-phase-gate/ skill-handoff-summary/ skill-task-continuity/ @@ -75,5 +85,6 @@ codex-skill-library/ Repository versioning, release flow, and validation steps are documented in [docs/publishing.md](docs/publishing.md). The continuity-suite release checklist lives in [docs/release-checklist-long-task-suite.md](docs/release-checklist-long-task-suite.md). +Protocol migration and overview docs live in [docs/context-protocol-migration.md](docs/context-protocol-migration.md) and [docs/long-task-suite.md](docs/long-task-suite.md). Package-level install guidance stays in each package README. If you are publishing this repository for the first time, start with those maintainer docs instead of the package runtime docs. diff --git a/README.zh-CN.md b/README.zh-CN.md index 7d6b2ea..1a36dc0 100644 --- a/README.zh-CN.md +++ b/README.zh-CN.md @@ -26,7 +26,9 @@ | Skill | 适用场景 | 文档 | | --- | --- | --- | | `skill-governance` | 用任务式入口治理 skill 资产，包括新增、启用、体检、修复、审计和补文档 | [EN](skills/skill-governance/README.md) / [中文](skills/skill-governance/README.zh-CN.md) | -| `skill-context-keeper` | 刷新当前任务状态，不扩展成检查点或交接职责 | [EN](skills/skill-context-keeper/README.md) / [中文](skills/skill-context-keeper/README.zh-CN.md) | +| `skill-context-keeper` | 刷新并压缩可信的 root-task state | [EN](skills/skill-context-keeper/README.md) / [中文](skills/skill-context-keeper/README.zh-CN.md) | +| `skill-subtask-context` | 打开并维护有边界的 child-task state，避免 root summary 持续膨胀 | [EN](skills/skill-subtask-context/README.md) / [中文](skills/skill-subtask-context/README.zh-CN.md) | +| `skill-context-packet` | 为 root 或 subtask 工作写下一轮最小上下文 packet | [EN](skills/skill-context-packet/README.md) / [中文](skills/skill-context-packet/README.zh-CN.md) | | `skill-phase-gate` | 在有分量的改动前后加入 preflight / postflight 检查点 | [EN](skills/skill-phase-gate/README.md) / [中文](skills/skill-phase-gate/README.zh-CN.md) | | `skill-handoff-summary` | 在暂停或换人时生成紧凑、面向续做的交接摘要 | [EN](skills/skill-handoff-summary/README.md) / [中文](skills/skill-handoff-summary/README.zh-CN.md) | | `skill-task-continuity` | 负责连续性套件的启动与组合，但不替代原子包 | [EN](skills/skill-task-continuity/README.md) / [中文](skills/skill-task-continuity/README.zh-CN.md) | @@ -36,7 +38,7 @@ 1. 先看 [skills/README.zh-CN.md](skills/README.zh-CN.md) 浏览当前可用 skill。 2. 进入具体 skill 包的 `README.md` 了解它是否适合你的场景。 3. 按该包 README 中的安装说明安装目标包。 -4. 如果你需要整套连续性流程的启动或组合说明，先从 `skill-task-continuity` 开始；如果只需要单个动作，直接安装对应的原子包。 +4. 如果你需要整套连续性流程的启动或组合说明，先从 `skill-task-continuity` 开始；如果下一步动作已经明确，也可以直接进入 `skill-context-keeper`、`skill-subtask-context`、`skill-context-packet`、`skill-phase-gate` 或 `skill-handoff-summary`。 5. 现在可先阅读该包下的参考页了解边界说明，后续阶段再继续使用其中补充的示例与提示词资料。 ## 阅读入口 @@ -45,9 +47,15 @@ - 中文技能索引: [skills/README.zh-CN.md](skills/README.zh-CN.md) - `skill-governance` 包说明: [EN](skills/skill-governance/README.md) / [中文](skills/skill-governance/README.zh-CN.md) - `skill-context-keeper` 包说明: [EN](skills/skill-context-keeper/README.md) / [中文](skills/skill-context-keeper/README.zh-CN.md) +- `skill-subtask-context` 包说明: [EN](skills/skill-subtask-context/README.md) / [中文](skills/skill-subtask-context/README.zh-CN.md) +- `skill-context-packet` 包说明: [EN](skills/skill-context-packet/README.md) / [中文](skills/skill-context-packet/README.zh-CN.md) - `skill-phase-gate` 包说明: [EN](skills/skill-phase-gate/README.md) / [中文](skills/skill-phase-gate/README.zh-CN.md) - `skill-handoff-summary` 包说明: [EN](skills/skill-handoff-summary/README.md) / [中文](skills/skill-handoff-summary/README.zh-CN.md) - `skill-task-continuity` 包说明: [EN](skills/skill-task-continuity/README.md) / [中文](skills/skill-task-continuity/README.zh-CN.md) +- English context protocol migration guide: [docs/context-protocol-migration.md](docs/context-protocol-migration.md) +- 中文迁移说明: [docs/context-protocol-migration.zh-CN.md](docs/context-protocol-migration.zh-CN.md) +- English continuity suite overview: [docs/long-task-suite.md](docs/long-task-suite.md) +- 中文连续性套件总览: [docs/long-task-suite.zh-CN.md](docs/long-task-suite.zh-CN.md) - English publishing guide: [docs/publishing.md](docs/publishing.md) - 中文发布说明: [docs/publishing.zh-CN.md](docs/publishing.zh-CN.md) - English continuity-suite release checklist: [docs/release-checklist-long-task-suite.md](docs/release-checklist-long-task-suite.md) @@ -66,6 +74,8 @@ codex-skill-library/ README.zh-CN.md skill-governance/ skill-context-keeper/ + skill-subtask-context/ + skill-context-packet/ skill-phase-gate/ skill-handoff-summary/ skill-task-continuity/ @@ -75,5 +85,6 @@ codex-skill-library/ 仓库级的版本、发布流程和校验说明统一放在 [docs/publishing.zh-CN.md](docs/publishing.zh-CN.md)。 连续性套件发布清单在 [docs/release-checklist-long-task-suite.zh-CN.md](docs/release-checklist-long-task-suite.zh-CN.md)。 +协议迁移和套件总览放在 [docs/context-protocol-migration.zh-CN.md](docs/context-protocol-migration.zh-CN.md) 与 [docs/long-task-suite.zh-CN.md](docs/long-task-suite.zh-CN.md)。 包级安装说明统一保留在各自 README 中。 如果你是第一次发布这个仓库，建议先看这些维护者文档，而不是直接从包内运行时说明开始。 diff --git a/docs/context-protocol-migration.md b/docs/context-protocol-migration.md new file mode 100644 index 0000000..d94effc --- /dev/null +++ b/docs/context-protocol-migration.md @@ -0,0 +1,131 @@ +# Context Protocol Migration Guide + +## Who This Is For + +Use this guide if you already know the older long-task continuity suite and need to understand what changed. + +You can ignore this guide if: + +- you are starting fresh with the current six-package suite +- you only need one atomic package and do not care about the broader workflow +- you are reading package docs directly and do not need the historical bridge + +## Why The Model Changed + +The older continuity framing was useful, but it still treated too much work as “state vs gate vs handoff.” +That left two important jobs under-modeled: + +- isolated child-task context +- minimum next-turn context injection + +The context protocol makes both of those first-class. + +## Old Model vs New Model + +| Older Mental Model | Context Protocol Replacement | +| --- | --- | +| One task state that keeps growing | Separate `root/` state from `subtasks/` state | +| Summaries are the main continuity object | Packets become the default next-turn injection object | +| `skill-phase-gate` often feels central | `skill-phase-gate` is now an optional checkpoint only | +| Handoff is mostly a flat `.agent-state/HANDOFF.md` | Handoff can target root or subtask scope | +| Orchestration is mainly about four packages | Suite routing now spans six packages and a layered repo layout | + +## Package Mapping + +### Still The Same In Spirit + +- `skill-context-keeper` + - still owns trusted root-task refresh + - now explicitly owns root-state compression too +- `skill-handoff-summary` + - still owns continuation-oriented pause artifacts + - now works for both root and subtask scope +- `skill-task-continuity` + - still owns bootstrap and package routing + - now boots a layered protocol layout instead of a flat one + +### Newly First-Class + +- `skill-subtask-context` + - owns bounded child-task state under `.agent-state/subtasks//` +- `skill-context-packet` + - owns minimum next-turn packets under `.agent-state/root/PACKET.md` or `.agent-state/subtasks//PACKET.md` + +### Narrowed On Purpose + +- `skill-phase-gate` + - no longer acts like the center of continuity + - only adds an optional operational checkpoint around risky work + +## How To Adopt The New Workflow + +### Recommended Path + +1. Start in beginner mode. +2. Bootstrap `AGENTS.md`, `.agent-state/INDEX.md`, and `.agent-state/root/`. +3. Keep using `skill-context-keeper` for root-state refresh. +4. When the root summary gets noisy, split one bounded child task with `skill-subtask-context`. +5. When the next turn does not need the whole state file, create a packet with `skill-context-packet`. +6. Use `skill-phase-gate` only when the checkpoint itself adds value. +7. Use `skill-handoff-summary` whenever work pauses or ownership changes. + +### Beginner Mode + +You usually only need: + +- `.agent-state/INDEX.md` +- `.agent-state/root/TASK_STATE.md` +- `.agent-state/root/PACKET.md` +- `.agent-state/root/HANDOFF.md` + +Stay here until you have a real child task with a different owner, scope, or risk boundary. + +### Expanded Mode + +Move into expanded mode when at least one of these becomes true: + +- the root task is carrying too much unrelated local detail +- another agent should own a bounded slice of the work +- packet-sized continuation is better than loading the whole root summary +- archived stale detail is making active state unreadable + +## Common Mistakes + +### Treating Packets As Full State + +Packets are not the durable canonical record. +They are the minimum next-turn injection object. +If you keep shoving full history into packets, you lose the point of compression. + +### Keeping Child-Task Detail In Root State + +If a child task has its own files, risks, and exit criteria, give it its own state. +Otherwise the root summary becomes the place where all context goes to rot. + +### Using `skill-phase-gate` As The Continuity Center + +If the main problem is stale state, use `skill-context-keeper`. +If the main problem is bounded child-task isolation, use `skill-subtask-context`. +If the main problem is context budget, use `skill-context-packet`. + +### Writing Handoffs For Work That Is Not Actually Pausing + +If the work is still live and the next turn just needs a small injection surface, write a packet instead of a handoff. + +## What Does Not Change + +- public install paths stay under `skills//` +- the suite is still repo-first and documentation-first +- routing remains narrow on purpose +- static evals remain the maintainer regression surface + +## Quick Decision Table + +| Need | Use | +| --- | --- | +| Refresh the main task picture | `skill-context-keeper` | +| Open or refresh a child task | `skill-subtask-context` | +| Shrink the next turn into minimal context | `skill-context-packet` | +| Add a risky-change checkpoint | `skill-phase-gate` | +| Pause or transfer with a durable note | `skill-handoff-summary` | +| Bootstrap the suite or choose the next package | `skill-task-continuity` | diff --git a/docs/context-protocol-migration.zh-CN.md b/docs/context-protocol-migration.zh-CN.md new file mode 100644 index 0000000..e27508c --- /dev/null +++ b/docs/context-protocol-migration.zh-CN.md @@ -0,0 +1,131 @@ +# Context Protocol 迁移指南 + +## 这份文档适合谁 + +如果你已经熟悉旧版长任务连续性套件，但需要理解这次模型变化，就看这份文档。 + +如果你属于下面这些情况，可以跳过它： + +- 你是第一次直接使用当前六包套件 +- 你只需要一个原子包，不关心整个工作流 +- 你直接看包内 README，不需要历史桥接说明 + +## 为什么要改模型 + +旧版连续性框架是有用的，但它仍然把太多事情都归到“state vs gate vs handoff”里。 +这让两个关键能力长期处于弱建模状态： + +- 有隔离边界的 child-task context +- 下一轮最小上下文注入 + +`context protocol` 把这两件事提升成了一等对象。 + +## 旧模型 vs 新模型 + +| 旧心智模型 | Context Protocol 中的替代物 | +| --- | --- | +| 只有一份持续膨胀的 task state | 把 `root/` state 和 `subtasks/` state 分开 | +| summary 是主要的连续性对象 | packet 成为默认的 next-turn injection object | +| `skill-phase-gate` 经常像连续性中心 | `skill-phase-gate` 现在只是 optional checkpoint | +| handoff 基本等于扁平的 `.agent-state/HANDOFF.md` | handoff 现在可以作用在 root 或 subtask 范围 | +| orchestration 主要围绕四个包 | 现在是六个包加一套分层 repo layout | + +## 包映射关系 + +### 精神上仍然延续的部分 + +- `skill-context-keeper` + - 仍然负责可信的 root-task refresh + - 现在也显式负责 root-state compression +- `skill-handoff-summary` + - 仍然负责 continuation-oriented pause artifact + - 现在同时支持 root 和 subtask scope +- `skill-task-continuity` + - 仍然负责 bootstrap 和 package routing + - 现在启动的是分层协议布局，而不是扁平布局 + +### 新增的一等能力 + +- `skill-subtask-context` + - 负责 `.agent-state/subtasks//` 下的 bounded child-task state +- `skill-context-packet` + - 负责 `.agent-state/root/PACKET.md` 或 `.agent-state/subtasks//PACKET.md` 下的最小 next-turn packet + +### 被刻意收窄的部分 + +- `skill-phase-gate` + - 不再充当连续性系统中心 + - 只在 risky work 周围提供 optional operational checkpoint + +## 如何采用新的工作流 + +### 推荐路径 + +1. 先从 beginner mode 开始。 +2. bootstrap `AGENTS.md`、`.agent-state/INDEX.md` 和 `.agent-state/root/`。 +3. 继续用 `skill-context-keeper` 做 root-state refresh。 +4. 当 root summary 开始嘈杂时，用 `skill-subtask-context` 拆出一个有边界的 child task。 +5. 当下一轮不需要整份 state 文件时，用 `skill-context-packet` 写 packet。 +6. 只有当 checkpoint 本身真的有价值时，才使用 `skill-phase-gate`。 +7. 当工作暂停或换人时，再用 `skill-handoff-summary`。 + +### Beginner Mode + +大多数时候你只需要： + +- `.agent-state/INDEX.md` +- `.agent-state/root/TASK_STATE.md` +- `.agent-state/root/PACKET.md` +- `.agent-state/root/HANDOFF.md` + +在你真正出现不同 owner、不同 scope 或不同 risk boundary 的 child task 之前，都可以停留在这里。 + +### Expanded Mode + +当下面任意一点成立时，再进入 expanded mode： + +- root task 已经带了太多互不相关的局部细节 +- 另一位 agent 应该接手一段有边界的工作 +- packet-sized continuation 比加载整份 root summary 更合理 +- stale detail 已经让 active state 难以阅读 + +## 常见误区 + +### 把 Packet 当成 Full State + +packet 不是持久的 canonical record。 +它是最小 next-turn injection object。 +如果你持续把完整历史塞进 packet，就失去了压缩的意义。 + +### 把 Child-Task 细节继续堆在 Root State 里 + +如果一个 child task 已经有自己的文件、风险和退出条件，就应该给它自己的 state。 +否则 root summary 很快就会变成所有上下文腐烂的地方。 + +### 继续把 `skill-phase-gate` 当成连续性中心 + +如果主要问题是 stale state，用 `skill-context-keeper`。 +如果主要问题是 bounded child-task isolation，用 `skill-subtask-context`。 +如果主要问题是 context budget，用 `skill-context-packet`。 + +### 工作并未暂停却去写 Handoff + +如果工作还在持续，下一轮只是需要一个更小的注入面，那就应该写 packet，而不是 handoff。 + +## 不变的部分 + +- 对外安装路径仍然保持在 `skills//` +- 套件仍然是 repo-first、documentation-first +- 路由边界仍然刻意保持狭窄 +- static evals 仍然是维护者的主要回归面 + +## 快速决策表 + +| 需要什么 | 用哪个包 | +| --- | --- | +| 刷新主任务图景 | `skill-context-keeper` | +| 打开或刷新 child task | `skill-subtask-context` | +| 把下一轮压成最小上下文 | `skill-context-packet` | +| 为 risky change 加 checkpoint | `skill-phase-gate` | +| 在暂停或转交前留下 durable note | `skill-handoff-summary` | +| 启动套件或决定下一个包 | `skill-task-continuity` | diff --git a/docs/long-task-suite.md b/docs/long-task-suite.md index 6edd5fa..a26745f 100644 --- a/docs/long-task-suite.md +++ b/docs/long-task-suite.md @@ -2,97 +2,116 @@ ## Problem Statement -Long threads usually do not fail all at once. They fail by degrees: the shared state gets stale, the workflow loses its shape, and handoffs become too thin for the next agent to trust. +Long-running work rarely fails in one dramatic moment. +It drifts. -This suite exists to make those failure modes explicit. It treats long-task degradation as three separate problems: +- root state becomes stale or bloated +- child-task details leak into the wrong place +- the next turn loads too much context +- risky edits lose checkpoints +- pauses leave the next agent guessing -- state drift, where the working picture no longer matches reality -- workflow drift, where the task stops following a deliberate sequence of phases and checkpoints -- handoff friction, where another agent cannot resume without guessing +The context protocol exists to make those failure modes explicit and routable. +Instead of treating “continuity” as one vague summary problem, the suite separates root state, subtask state, packet compression, checkpoints, and handoffs. -The goal is not to add more ceremony. The goal is to make continuity measurable so that long tasks stay resumable, inspectable, and transferable. +## The Context Protocol -## State Drift, Workflow Drift, And Handoff Friction +The current suite is organized around three state layers: -These three failure modes overlap, but they are not the same thing. +- **Root state:** the durable top-level picture for the main task +- **Subtask state:** bounded child-task context that should not pollute the root summary +- **Packets:** the minimum context object for the next root or subtask turn -State drift appears when summaries, context, or task memory lag behind the actual work. The risk is silent divergence: the thread sounds confident while carrying the wrong assumptions. +These layers are backed by a repo-first starter layout: -Workflow drift appears when a task that needs staged execution starts behaving like a single shot. The work may still move forward, but it loses checkpoints, decision points, and clear boundaries. +- `AGENTS.md` +- `.agent-state/INDEX.md` +- `.agent-state/root/` +- `.agent-state/subtasks/` +- `.agent-state/archive/` -Handoff friction appears when a pause or transfer leaves too little signal for the next agent. The work is not necessarily wrong, just expensive to resume. - -The suite uses these distinctions to decide which package should trigger and which one should stay out of the way. - -The evaluation matrix uses normalized artifact paths and event tokens so the runner can validate results consistently. +Beginner mode usually stays in `INDEX.md` plus `.agent-state/root/`. +Expanded mode starts when work is split into child tasks or archived into packet-sized continuation objects. ## Package Map | Package | Responsibility | Trigger Shape | | --- | --- | --- | -| `skill-context-keeper` | Preserve and reconstruct working state across long threads, especially after interruptions or stale summaries. | Resume, refresh, or reconcile context. | -| `skill-phase-gate` | Decide when work needs phase boundaries, checkpoints, or a deliberate pause before execution continues. | Split, gate, or stage the work. | -| `skill-handoff-summary` | Produce a clean transfer note when work is paused or handed to another agent. | Summarize status, blockers, and next steps. | -| `skill-task-continuity` | Orchestrate the three atomic packages when the task itself is about maintaining long-thread continuity. | Bootstrap the suite, coordinate boundaries, and keep the flow coherent. | +| `skill-context-keeper` | Refresh and compress trusted root-task state. | The root task is active but stale, noisy, or bloated. | +| `skill-subtask-context` | Open, refresh, or close bounded child-task state. | A child task needs its own local scope and restart state. | +| `skill-context-packet` | Write the minimum context packet for the next turn. | The next step needs less than a full state file. | +| `skill-phase-gate` | Add an optional operational checkpoint around risky work. | A meaningful multi-file change needs explicit preflight or postflight control. | +| `skill-handoff-summary` | Capture a compact root or subtask handoff. | Work is about to pause, transfer, or cross sessions. | +| `skill-task-continuity` | Bootstrap the suite and route to the correct atomic package. | A repo needs starter files, protocol guidance, or package-selection help. | -## Repository Boundary Rules +## Compatibility And Migration -This repository is a public installable skill library, so the suite docs must stay reader-facing and maintainable. +If you previously thought of this suite as four packages that handled “state, gates, handoff, and orchestration,” you should read the migration guide: -- Keep the suite spec in `docs/`, not in live agent state files. -- Do not create a root `AGENTS.md`, `.agent-state/`, or public-package `.agents/skills` content for this task. -- Treat `evals/cases.csv` as the source of truth for trigger coverage, but keep the prose docs understandable on their own. -- Describe package boundaries in plain language; do not require readers to open package implementation files first. -- Prefer the narrowest package that matches the prompt. The composition package should not steal work that belongs to an atomic package. -- Make ambiguity explicit in the matrix so maintainers can see when a keyword match is not a real trigger. +- [docs/context-protocol-migration.md](context-protocol-migration.md) +- [docs/context-protocol-migration.zh-CN.md](context-protocol-migration.zh-CN.md) -## Success Criteria - -### Outcome +The short version: -- Long-thread work can be resumed, paused, or transferred without losing intent. -- The suite catches both false positives and false negatives for the four target packages. -- A maintainer can understand the architecture and boundaries without opening package source files. +- root-state refresh still belongs to `skill-context-keeper` +- `skill-phase-gate` is no longer the continuity center +- subtask isolation now has a first-class owner: `skill-subtask-context` +- minimal next-turn injection now has a first-class owner: `skill-context-packet` -### Process +## Repository Boundary Rules -- The eval matrix includes positive trigger cases and negative trigger cases for every atomic package. -- The matrix includes at least one composition-package bootstrap case and one boundary-protection case. -- Each case records the expected artifacts and the expected workflow event or command shape when that matters. +This repository is a public installable skill library, so the suite docs must stay reader-facing and maintainable. -### Style +- Keep public architecture in `docs/`, not in live repo state files for this library itself. +- Treat `evals/cases.csv` as the normalized routing matrix, not as a private scratchpad. +- Prefer the narrowest package that matches the request. +- Do not let the suite entry package steal work that belongs to a single atomic package. +- Keep beginner-mode guidance obvious for users who do not need subtask splitting yet. +- Keep migration guidance explicit so older four-package users do not guess their way into the new model. -- The docs stay concise, public-reader-friendly, and easy to scan. -- English and Chinese versions share the same major section order. -- Trigger notes read like maintainer guidance, not like internal scratchpad text. +## Success Criteria -### Efficiency +The suite is successful when a downstream repo can follow this path without rereading a whole thread: -- Maintainers can validate the suite from the docs and CSV without reverse-engineering package code. -- The matrix is small enough to extend without becoming noisy. -- Ambiguous prompts are documented once, then reused as regression coverage. +1. bootstrap continuity starter files +2. refresh root state +3. split a bounded subtask +4. inject only a packet into the next execution turn +5. checkpoint a risky change when needed +6. pause with a valid handoff +7. resume from root or subtask artifacts without context bleed -## Initial Evaluation Matrix +## Seed Evaluation Matrix -The seed matrix lives in `evals/cases.csv`. The table below shows the initial coverage shape and the kinds of expected artifacts and workflow events to look for. +The seed matrix lives in `evals/cases.csv`. +It now validates the protocol model rather than the older flat-layout model. | Case | Package | Trigger | Prompt Shape | Expected Artifacts | Expected Events | | --- | --- | --- | --- | --- | --- | -| `context_resume` | `skill-context-keeper` | Yes | Resume the last known state and carry forward unresolved work. | `state/context.snapshot`, `state/continuity.note` | `context:reload`, `context:reconstruct`, `context:summary` | -| `context_resume_not_needed` | `skill-context-keeper` | No | Answer a one-off question with no continuity risk. | `none` | `context:skip`, `direct:answer` | -| `phase_gate_before_multi_step` | `skill-phase-gate` | Yes | Split a multi-step task into phases before coding starts. | `plan/phase.plan`, `plan/checkpoints.md`, `plan/exit-criteria.md` | `phase:split`, `phase:checkpoint`, `phase:gate` | -| `tiny_edit_not_gate` | `skill-phase-gate` | No | Make a tiny local edit with no staged workflow. | `none` | `phase:skip`, `direct:edit` | -| `handoff_before_pause` | `skill-handoff-summary` | Yes | Pause work and hand it to another agent. | `handoff/HANDOFF.md`, `handoff/blockers.md`, `handoff/next-steps.md` | `handoff:capture`, `handoff:pause`, `handoff:transfer` | -| `handoff_not_needed` | `skill-handoff-summary` | No | Give a final answer without transfer notes. | `none` | `handoff:skip`, `direct:answer` | -| `suite_bootstrap` | `skill-task-continuity` | Yes | Coordinate the long-task suite across the atomic packages. | `AGENTS.md`, `.agent-state/TASK_STATE.md`, `.agent-state/HANDOFF.md` | `bootstrap:agents_md`, `bootstrap:task_state`, `bootstrap:handoff` | -| `suite_boundary_clean` | `skill-task-continuity` | No | A trivial edit that merely mentions all the keywords. | `none` | `bootstrap:skip`, `direct:edit` | - -## Phase Plan - -The current task is the bootstrap phase: define the suite, seed the matrix, and make the boundaries legible. - -Phase 1 should keep the documentation stable while the package implementations are still being shaped. That means adding new cases only when they improve coverage, not when they repeat the same trigger in different words. - -Phase 2 should expand the matrix with more realistic long-thread scenarios, especially ones where the wrong package could plausibly trigger. - -Phase 3 should use the suite as a regression harness for future package changes, so trigger behavior stays narrow and intentional. +| `root_state_refresh` | `skill-context-keeper` | Yes | Refresh the root task picture from the repo. | `root/task_state` | `root:refresh`, `root:reconcile`, `root:compress` | +| `root_state_compress` | `skill-context-keeper` | Yes | Shrink bloated root state without opening a new packet-only flow. | `root/task_state` | `root:refresh`, `root:reconcile`, `root:compress` | +| `root_state_refresh_not_needed` | `skill-context-keeper` | No | A trivial one-off ask with no continuity risk. | `none` | `root:skip`, `route:other` | +| `subtask_split_from_root` | `skill-subtask-context` | Yes | Split bounded child work from the root thread. | `subtask/task_state` | `subtask:split`, `subtask:refresh`, `subtask:isolate` | +| `subtask_resume_from_packet` | `skill-subtask-context` | Yes | Refresh local state for a child task resumed from a packet. | `subtask/task_state` | `subtask:split`, `subtask:refresh`, `subtask:isolate` | +| `subtask_state_not_needed` | `skill-subtask-context` | No | Stay in root state; do not open a child task. | `none` | `subtask:skip`, `route:root_or_packet` | +| `packet_root_minimal_injection` | `skill-context-packet` | Yes | Compress the next root turn into a minimal packet. | `root/packet` | `packet:compose`, `packet:trim`, `packet:inject` | +| `packet_not_needed_for_full_refresh` | `skill-context-packet` | No | Do a full-state refresh instead of packet compression. | `none` | `packet:skip`, `route:state_or_handoff` | +| `phase_gate_risky_checkpoint` | `skill-phase-gate` | Yes | Add a checkpoint around risky multi-file work. | `phase/preflight`, `phase/postflight` | `phase:preflight`, `phase:checkpoint`, `phase:postflight` | +| `tiny_edit_not_gate` | `skill-phase-gate` | No | Make a trivial local edit. | `none` | `phase:skip`, `direct:edit` | +| `handoff_subtask_pause` | `skill-handoff-summary` | Yes | Pause a child task and leave a restart note. | `subtask/handoff` | `handoff:capture`, `handoff:pause`, `handoff:resume` | +| `handoff_not_needed` | `skill-handoff-summary` | No | Give a final answer with no continuation artifact. | `none` | `handoff:skip`, `direct:answer` | +| `suite_bootstrap_protocol` | `skill-task-continuity` | Yes | Bootstrap the protocol and route across the suite. | `suite/agents`, `suite/index`, root and subtask templates | `suite:bootstrap`, `suite:route`, `suite:explain` | +| `suite_boundary_clean` | `skill-task-continuity` | No | Mention continuity keywords inside a trivial README fix. | `none` | `suite:skip`, `direct:edit` | + +## Validation Strategy + +The current static harness checks: + +- routing polarity +- exact event namespaces +- strict artifact mapping +- required file presence +- workflow-doc coverage +- boundary language in published docs + +That gives maintainers a regression surface for the protocol without requiring live model execution. diff --git a/docs/long-task-suite.zh-CN.md b/docs/long-task-suite.zh-CN.md index 8fe1de1..569f667 100644 --- a/docs/long-task-suite.zh-CN.md +++ b/docs/long-task-suite.zh-CN.md @@ -2,97 +2,115 @@ ## 问题陈述 -长线程通常不是一次性坏掉的，而是逐步退化：共享状态开始过时，工作流失去节奏，交接信息也变得不足以让下一位执行者放心接手。 +长任务很少是一次性坏掉的。 +它更常见的失败方式是逐步漂移： -这套文档要解决的，就是把这些退化模式说清楚。我们把长任务中的失效拆成三类： +- root state 变旧、变散、变臃肿 +- child-task 细节泄漏到不该去的地方 +- 下一轮加载了过多上下文 +- risky edit 缺少 checkpoint +- 暂停后让下一位执行者靠猜继续 -- 状态漂移，也就是工作认知和真实进展开始脱节 -- 流程漂移，也就是本来需要分阶段推进的任务变成了没有检查点的直冲 -- 交接摩擦，也就是换人之后需要靠猜才能继续 +`context protocol` 的目标，就是把这些退化模式变成可路由、可验证、可维护的对象。 +它不再把“连续性”当成一个模糊的摘要问题，而是明确拆成 root state、subtask state、packet compression、checkpoint 和 handoff。 -目标不是增加仪式感，而是让连续性变成可观察、可验证、可维护的东西。只有这样，长任务才更容易恢复、审阅和转交。 +## Context Protocol -## 状态漂移、流程漂移、与交接摩擦 +当前套件围绕三层状态组织： -这三种问题彼此相关，但并不相同。 +- **Root state：** 主任务的持久顶层图景 +- **Subtask state：** 不应该污染 root summary 的局部子任务上下文 +- **Packet：** 下一轮 root 或 subtask 执行真正需要的最小上下文对象 -状态漂移通常表现为摘要、上下文或任务记忆已经跟不上真实工作进度。它最大的风险是悄悄偏离：线程表面上很顺，实际上已经带着错误前提继续往前走。 +这三层默认落在一个 repo-first 的启动布局里： -流程漂移则发生在需要分阶段推进的任务被当成一次性动作处理。工作可能还在继续，但检查点、决策点和边界感都会变弱。 +- `AGENTS.md` +- `.agent-state/INDEX.md` +- `.agent-state/root/` +- `.agent-state/subtasks/` +- `.agent-state/archive/` -交接摩擦出现在暂停或转交之后，下一位执行者拿到的信息不够完整，必须重新猜测当前状态。问题不一定是错误，但一定会增加恢复成本。 - -这个套件就是用这三种差异来决定：哪些包应该触发，哪些包不该被卷进来。 - -评估矩阵里的产物和事件都使用了规范化的路径和值，这样后续执行器就能稳定校验，而不是依赖自然语言猜测。 +Beginner mode 通常只使用 `INDEX.md` 和 `.agent-state/root/`。 +当任务需要拆子任务，或者需要把活跃上下文压成 packet 并移入 archive 时，才进入 expanded mode。 ## 包结构图 | 包 | 职责 | 触发形态 | | --- | --- | --- | -| `skill-context-keeper` | 在长线程中保存和重建工作状态，尤其适合处理中断或过时摘要后的恢复。 | 恢复、刷新、或对齐上下文。 | -| `skill-phase-gate` | 判断任务是否需要阶段边界、检查点，或在继续执行前先停一下。 | 拆分、门控、或分阶段推进。 | -| `skill-handoff-summary` | 在任务暂停或转交时产出清晰的交接说明。 | 总结状态、阻塞点和下一步。 | -| `skill-task-continuity` | 当任务本身就是为了维持长线程连续性时，统筹前三个原子包。 | 启动套件、协调边界、保持流程连贯。 | - -## 仓库边界规则 +| `skill-context-keeper` | 刷新并压缩可信的 root-task state | root 任务还在继续，但当前图景已经过时、嘈杂或过大 | +| `skill-subtask-context` | 打开、刷新或关闭有边界的 child-task state | 某段工作需要自己的局部范围和重启状态 | +| `skill-context-packet` | 为下一轮写最小上下文 packet | 下一步只需要比完整 state 更小的注入面 | +| `skill-phase-gate` | 为 risky work 加一个可选操作检查点 | 有分量的多文件改动需要显式 preflight / postflight | +| `skill-handoff-summary` | 生成 root 或 subtask 的紧凑 handoff | 工作即将暂停、转交或跨 session | +| `skill-task-continuity` | 启动套件并路由到正确的原子包 | repo 需要 starter files、协议说明或选包帮助 | -这个仓库是公开可安装的 skill 库，所以套件文档必须尽量面向读者，且便于维护。 +## 兼容与迁移 -- 套件规范放在 `docs/`，不要写进运行中的 agent 状态文件。 -- 本任务不要创建根目录 `AGENTS.md`、`.agent-state/`，也不要写入 public-package 的 `.agents/skills` 内容。 -- `evals/cases.csv` 是触发覆盖的事实来源，但正文也要能独立读懂。 -- 先用通俗语言解释包边界，不要要求读者先去看实现文件。 -- 能匹配原子包的就优先匹配原子包，组合包不应该抢走本该由原子包处理的工作。 -- 把模糊情况写进矩阵，方便维护者看到“只是关键词出现”并不等于真正触发。 +如果你之前把这套东西理解成“4 个包分别负责状态、gate、handoff 和 orchestration”，现在应该看迁移说明： -## 成功标准 +- [docs/context-protocol-migration.md](context-protocol-migration.md) +- [docs/context-protocol-migration.zh-CN.md](context-protocol-migration.zh-CN.md) -### 结果 +短版结论是： -- 长任务可以在不中断意图的情况下恢复、暂停或转交。 -- 套件能覆盖四个目标包的误触发和漏触发情况。 -- 维护者不看包源码，也能理解整体架构和边界。 +- root-state refresh 仍然归 `skill-context-keeper` +- `skill-phase-gate` 不再是连续性系统中心 +- subtask isolation 现在有了一等所有者：`skill-subtask-context` +- 最小下一轮注入现在有了一等所有者：`skill-context-packet` -### 过程 +## 仓库边界规则 -- 每个原子包都要有正触发和负触发用例。 -- 矩阵里要有组合包的启动用例，也要有边界保护用例。 -- 每个案例都要写清楚期望产物，以及必要时对应的工作流事件或命令形态。 +这个仓库是公开可安装的 skill library，所以套件说明必须保持面向读者、便于维护。 -### 风格 +- 公开架构说明放在 `docs/`，不要写进这个 public library 自己的 live repo state 文件里。 +- 把 `evals/cases.csv` 当成规范化路由矩阵，而不是内部草稿。 +- 能匹配单个原子包时，就不要让 suite entry package 抢走任务。 +- Beginner mode 必须对多数用户足够明显，不要求大家一开始就拆 subtasks。 +- 迁移说明必须足够直接，避免旧四包用户靠猜来理解新模型。 -- 文档要简洁、面向读者、易于扫读。 -- 英文版和中文版保持相同的主要章节顺序。 -- 触发说明要像维护建议，不要像内部草稿。 +## 成功标准 -### 效率 +当下游 repo 可以在不重读整条线程的前提下走完这条路径时，这套东西才算成功： -- 维护者可以只看文档和 CSV 就完成验证，不需要反推包实现。 -- 矩阵要足够小，方便持续扩展，而不是越写越乱。 -- 模糊提示只需要定义一次，之后就能作为回归覆盖重复使用。 +1. bootstrap continuity starter files +2. refresh root state +3. split a bounded subtask +4. inject only a packet into the next execution turn +5. checkpoint a risky change when needed +6. pause with a valid handoff +7. resume from root 或 subtask artifacts without context bleed -## 初始评估矩阵 +## 种子评估矩阵 -种子矩阵存放在 `evals/cases.csv`。下面这张表展示了初始覆盖的形状，以及在什么情况下应该关注哪些产物和流程事件。 +种子矩阵位于 `evals/cases.csv`。 +它现在校验的是 protocol model，而不是旧的扁平布局模型。 | 用例 | 包 | 是否触发 | 提示形态 | 期望产物 | 期望事件 | | --- | --- | --- | --- | --- | --- | -| `context_resume` | `skill-context-keeper` | 是 | 恢复最后已知状态，并把未完成工作带下去。 | `state/context.snapshot`、`state/continuity.note` | `context:reload`、`context:reconstruct`、`context:summary` | -| `context_resume_not_needed` | `skill-context-keeper` | 否 | 回答一个一次性问题，没有连续性风险。 | `none` | `context:skip`、`direct:answer` | -| `phase_gate_before_multi_step` | `skill-phase-gate` | 是 | 在开始编码前先把多步骤任务拆成阶段。 | `plan/phase.plan`、`plan/checkpoints.md`、`plan/exit-criteria.md` | `phase:split`、`phase:checkpoint`、`phase:gate` | -| `tiny_edit_not_gate` | `skill-phase-gate` | 否 | 只做一个很小的本地修改，不需要分阶段。 | `none` | `phase:skip`、`direct:edit` | -| `handoff_before_pause` | `skill-handoff-summary` | 是 | 暂停工作并交给另一个执行者。 | `handoff/HANDOFF.md`、`handoff/blockers.md`、`handoff/next-steps.md` | `handoff:capture`、`handoff:pause`、`handoff:transfer` | -| `handoff_not_needed` | `skill-handoff-summary` | 否 | 直接给最终答案，不需要转交说明。 | `none` | `handoff:skip`、`direct:answer` | -| `suite_bootstrap` | `skill-task-continuity` | 是 | 协调长任务套件，让三个原子包一起工作。 | `AGENTS.md`、`.agent-state/TASK_STATE.md`、`.agent-state/HANDOFF.md` | `bootstrap:agents_md`、`bootstrap:task_state`、`bootstrap:handoff` | -| `suite_boundary_clean` | `skill-task-continuity` | 否 | 一个很小的编辑，只是碰巧提到了所有关键词。 | `none` | `bootstrap:skip`、`direct:edit` | - -## 阶段计划 - -当前任务本身就是引导阶段：先定义套件、先种下矩阵、先把边界讲清楚。 - -第一阶段要先把文档稳定下来，等包实现逐步成形后，再按需补充新的用例。重点不是堆数量，而是补能提高覆盖质量的案例。 - -第二阶段可以扩展成更接近真实长线程的场景，尤其是那些容易让错误包误触发的情况。 - -第三阶段则是把这套矩阵变成后续改动的回归护栏，确保触发行为一直保持窄而明确。 +| `root_state_refresh` | `skill-context-keeper` | 是 | 从 repo 刷新 root task 图景 | `root/task_state` | `root:refresh`、`root:reconcile`、`root:compress` | +| `root_state_compress` | `skill-context-keeper` | 是 | 压缩 bloated root state，但不转成 packet-only 流程 | `root/task_state` | `root:refresh`、`root:reconcile`、`root:compress` | +| `root_state_refresh_not_needed` | `skill-context-keeper` | 否 | 没有连续性风险的一次性小问题 | `none` | `root:skip`、`route:other` | +| `subtask_split_from_root` | `skill-subtask-context` | 是 | 把有边界的 child work 从 root 线程拆出去 | `subtask/task_state` | `subtask:split`、`subtask:refresh`、`subtask:isolate` | +| `subtask_resume_from_packet` | `skill-subtask-context` | 是 | 从 packet 恢复 child task 并刷新局部状态 | `subtask/task_state` | `subtask:split`、`subtask:refresh`、`subtask:isolate` | +| `subtask_state_not_needed` | `skill-subtask-context` | 否 | 留在 root state，不打开 child task | `none` | `subtask:skip`、`route:root_or_packet` | +| `packet_root_minimal_injection` | `skill-context-packet` | 是 | 把下一轮 root turn 压成最小 packet | `root/packet` | `packet:compose`、`packet:trim`、`packet:inject` | +| `packet_not_needed_for_full_refresh` | `skill-context-packet` | 否 | 需要 full-state refresh，而不是 packet compression | `none` | `packet:skip`、`route:state_or_handoff` | +| `phase_gate_risky_checkpoint` | `skill-phase-gate` | 是 | 为 risky multi-file work 加 checkpoint | `phase/preflight`、`phase/postflight` | `phase:preflight`、`phase:checkpoint`、`phase:postflight` | +| `tiny_edit_not_gate` | `skill-phase-gate` | 否 | 只做一个 trivial local edit | `none` | `phase:skip`、`direct:edit` | +| `handoff_subtask_pause` | `skill-handoff-summary` | 是 | 暂停 child task 并留下 restart note | `subtask/handoff` | `handoff:capture`、`handoff:pause`、`handoff:resume` | +| `handoff_not_needed` | `skill-handoff-summary` | 否 | 直接给最终答案，不需要 continuation artifact | `none` | `handoff:skip`、`direct:answer` | +| `suite_bootstrap_protocol` | `skill-task-continuity` | 是 | bootstrap protocol 并在套件内路由 | `suite/agents`、`suite/index`、root/subtask templates | `suite:bootstrap`、`suite:route`、`suite:explain` | +| `suite_boundary_clean` | `skill-task-continuity` | 否 | trivial README fix 中顺带提到了 continuity 关键词 | `none` | `suite:skip`、`direct:edit` | + +## 校验策略 + +当前静态 harness 会检查： + +- 路由正负向 +- 精确事件命名空间 +- 严格产物映射 +- required file 存在性 +- workflow 文档覆盖 +- 已发布文档里的边界语言 + +这让维护者可以在不运行 live model 的情况下，把 protocol 当成可回归校验的对象。 diff --git a/docs/publishing.md b/docs/publishing.md index 9a5f88d..9d734b2 100644 --- a/docs/publishing.md +++ b/docs/publishing.md @@ -13,11 +13,12 @@ Use this guide if you are maintaining the repository itself rather than using on - keep install paths stable for `skill-installer` - keep repository docs clean and easy to read - keep package runtime docs separate from repository release notes +- make the six-package context protocol easy to validate and publish ## Recommended Release Flow -1. Review the package README files, repository indexes, and publishing docs for release clarity. -2. Update [CHANGELOG.md](../CHANGELOG.md) with reader-visible changes and confirm the intended tag for this release. +1. Review the package README files, repository indexes, migration docs, suite overview docs, and publishing docs for release clarity. +2. Update [CHANGELOG.md](../CHANGELOG.md) with reader-visible changes and determine the next `` from the actual release scope. 3. Run local package tests, eval tests, and the continuity seed matrix before opening or merging the PR. 4. Let the PR checks workflow confirm the same core package and eval contracts. 5. Run install smoke tests from a pushed release branch or from `main` before tagging. @@ -40,14 +41,21 @@ Additional packaging sanity for `skill-governance`: (cd skills/skill-governance && python3 scripts/manage_skill.py --validate-only) ``` -Long-task continuity suite validation: +Protocol-aware continuity validation: ```bash python3 -m unittest discover -s evals -p 'test_*.py' -v python3 evals/run_evals.py ``` -The suite runner now scores prompt polarity, event namespaces, and strict artifact mapping in addition to repository shape checks. +Before tagging, also spot-check: + +- [docs/context-protocol-migration.md](context-protocol-migration.md) +- [docs/context-protocol-migration.zh-CN.md](context-protocol-migration.zh-CN.md) +- [docs/long-task-suite.md](long-task-suite.md) +- [docs/long-task-suite.zh-CN.md](long-task-suite.zh-CN.md) + +The continuity runner now scores prompt polarity, event namespaces, and strict artifact mapping across root state, subtask state, packets, checkpoints, and handoffs. Routing quality also requires trigger guidance to remain visible in published `SKILL.md` and README files, and guardrail metadata is validated statically when optional columns are present. ## Pull Request Checks @@ -60,8 +68,8 @@ That workflow is intentionally small: it runs package test directories under `sk - Use repository-level tags such as `v0.1.0`, `v0.2.0`, and `v1.0.0`. - Increase the minor version for backward-compatible additions. - Increase the major version when package layout or workflow changes in a breaking way. -- Keep `skills/skill-governance` stable as the public install path. -- After withdrawing the original `v0.6.0` tag, the current long-task continuity publication target is `v0.6.1`. +- Keep public install paths stable under `skills//` unless a deliberate breaking release says otherwise. +- Derive the next `` from `CHANGELOG.md` and the actual reader-visible scope rather than reusing an older placeholder tag. ## Install Smoke Tests For The Continuity Packages @@ -72,6 +80,8 @@ tmpdir="$(mktemp -d)" for path in \ skills/skill-context-keeper \ + skills/skill-subtask-context \ + skills/skill-context-packet \ skills/skill-phase-gate \ skills/skill-handoff-summary \ skills/skill-task-continuity @@ -91,6 +101,8 @@ tmpdir="$(mktemp -d)" for path in \ skills/skill-context-keeper \ + skills/skill-subtask-context \ + skills/skill-context-packet \ skills/skill-phase-gate \ skills/skill-handoff-summary \ skills/skill-task-continuity @@ -109,6 +121,8 @@ tmpdir="$(mktemp -d)" for path in \ skills/skill-context-keeper \ + skills/skill-subtask-context \ + skills/skill-context-packet \ skills/skill-phase-gate \ skills/skill-handoff-summary \ skills/skill-task-continuity @@ -116,7 +130,7 @@ do python3 /scripts/install-skill-from-github.py \ --repo Golden-Promise/codex-skill-library \ --path "$path" \ - --ref v0.6.1 \ + --ref \ --dest "$tmpdir" done ``` diff --git a/docs/publishing.zh-CN.md b/docs/publishing.zh-CN.md index af00e45..4b54223 100644 --- a/docs/publishing.zh-CN.md +++ b/docs/publishing.zh-CN.md @@ -13,11 +13,12 @@ - 保持 `skill-installer` 可用的稳定安装路径 - 让仓库级说明清晰、规范、便于阅读 - 让 skill 包内运行时文档与仓库发布说明分层明确 +- 让六包版本的 context protocol 易于校验和发布 ## 推荐发布流程 -1. 检查各个 skill 包 README、仓库索引页和发布文档是否清晰、可发布。 -2. 在 [CHANGELOG.md](../CHANGELOG.md) 中更新对读者可见的改动，并确认本次发布的目标 tag。 +1. 检查各个 skill 包 README、仓库索引页、迁移说明、suite overview 和发布文档是否清晰、可发布。 +2. 在 [CHANGELOG.md](../CHANGELOG.md) 中更新对读者可见的改动，并根据真实发布范围确定下一个 ``。 3. 在打开或合并 PR 之前，先跑完包级测试、eval 测试和连续性种子矩阵。 4. 让 PR checks workflow 再次验证同一组核心包合同和 eval 合同。 5. 在打 tag 之前，先从已推送的发布分支或 `main` 跑一遍安装 smoke test。 @@ -40,15 +41,22 @@ done (cd skills/skill-governance && python3 scripts/manage_skill.py --validate-only) ``` -长任务连续性套件的校验方式： +面向 protocol 的连续性校验： ```bash python3 -m unittest discover -s evals -p 'test_*.py' -v python3 evals/run_evals.py ``` -套件运行器现在除了仓库形状检查之外，还会按提示词正负向、事件命名空间和严格产物映射来评分。 -路由评分还要求已发布的 `SKILL.md` 和 README 中保留触发提示，而可选的 guardrail 字段会以静态元数据合同来校验。 +打 tag 前，还应人工 spot-check： + +- [docs/context-protocol-migration.md](context-protocol-migration.md) +- [docs/context-protocol-migration.zh-CN.md](context-protocol-migration.zh-CN.md) +- [docs/long-task-suite.md](long-task-suite.md) +- [docs/long-task-suite.zh-CN.md](long-task-suite.zh-CN.md) + +连续性 runner 现在会跨 root state、subtask state、packet、checkpoint 和 handoff 评分提示词正负向、事件命名空间与严格产物映射。 +路由评分还要求已发布的 `SKILL.md` 和 README 中保留触发提示，而可选 guardrail 字段会以静态元数据合同来校验。 ## Pull Request Checks @@ -60,8 +68,8 @@ Pull request 应运行 [.github/workflows/pull-request-checks.yml](../.github/wo - 使用仓库级 tag，例如 `v0.1.0`、`v0.2.0`、`v1.0.0` - 向后兼容的增强提升次版本 - 如果包结构或工作流有破坏性变化，则提升主版本 -- 对外安装路径尽量保持稳定，例如 `skills/skill-governance` -- 由于原始 `v0.6.0` tag 已撤回，当前这次长任务连续性发布的目标版本应为 `v0.6.1` +- 对外安装路径尽量保持在 `skills//` 下，除非是明确的破坏性发布 +- 下一个 `` 应根据 `CHANGELOG.md` 和真实的读者可见范围来确定，而不是沿用旧占位版本 ## 连续性包的安装 Smoke Test @@ -72,6 +80,8 @@ tmpdir="$(mktemp -d)" for path in \ skills/skill-context-keeper \ + skills/skill-subtask-context \ + skills/skill-context-packet \ skills/skill-phase-gate \ skills/skill-handoff-summary \ skills/skill-task-continuity @@ -91,6 +101,8 @@ tmpdir="$(mktemp -d)" for path in \ skills/skill-context-keeper \ + skills/skill-subtask-context \ + skills/skill-context-packet \ skills/skill-phase-gate \ skills/skill-handoff-summary \ skills/skill-task-continuity @@ -109,6 +121,8 @@ tmpdir="$(mktemp -d)" for path in \ skills/skill-context-keeper \ + skills/skill-subtask-context \ + skills/skill-context-packet \ skills/skill-phase-gate \ skills/skill-handoff-summary \ skills/skill-task-continuity @@ -116,7 +130,7 @@ do python3 /scripts/install-skill-from-github.py \ --repo Golden-Promise/codex-skill-library \ --path "$path" \ - --ref v0.6.1 \ + --ref \ --dest "$tmpdir" done ``` diff --git a/docs/release-checklist-long-task-suite.md b/docs/release-checklist-long-task-suite.md index 18b8ec6..7064efe 100644 --- a/docs/release-checklist-long-task-suite.md +++ b/docs/release-checklist-long-task-suite.md @@ -7,13 +7,17 @@ Use this checklist when preparing the long-task continuity suite for merge, tag ## 1. Pre-Release Sanity - Confirm the worktree is clean: `git status --short` -- Confirm the release target is still `v0.6.1`; if more user-visible scope landed, recalculate before tagging. +- Confirm [CHANGELOG.md](../CHANGELOG.md) reflects the real release scope and use it to derive the next `` - Re-read the repository entry docs and indexes: - [README.md](../README.md) - [README.zh-CN.md](../README.zh-CN.md) - [skills/README.md](../skills/README.md) - [skills/README.zh-CN.md](../skills/README.zh-CN.md) -- Confirm [CHANGELOG.md](../CHANGELOG.md) matches the release scope and does not describe unfinished work. +- Re-read the protocol-facing maintainer docs: + - [docs/context-protocol-migration.md](context-protocol-migration.md) + - [docs/context-protocol-migration.zh-CN.md](context-protocol-migration.zh-CN.md) + - [docs/long-task-suite.md](long-task-suite.md) + - [docs/long-task-suite.zh-CN.md](long-task-suite.zh-CN.md) ## 2. Local Validation @@ -40,14 +44,16 @@ python3 evals/run_evals.py ## 3. Docs And Index Verification -- Confirm all four continuity packages are still discoverable from the root and `skills/` indexes. +- Confirm all six continuity packages are discoverable from the root and `skills/` indexes. - Confirm package descriptions remain non-overlapping: - - `skill-context-keeper` = state refresh only - - `skill-phase-gate` = checkpoint only - - `skill-handoff-summary` = handoff only - - `skill-task-continuity` = suite bootstrap and composition only + - `skill-context-keeper` = root-state refresh and compression + - `skill-subtask-context` = bounded child-task state + - `skill-context-packet` = minimum next-turn packet + - `skill-phase-gate` = optional checkpoint only + - `skill-handoff-summary` = root or subtask handoff only + - `skill-task-continuity` = suite bootstrap and routing only - Confirm package `README.md` install sections still point to the published `skills//` paths. -- Confirm the publishing guides still link to this checklist and to the continuity smoke-test commands. +- Confirm the publishing guides still link to this checklist and to the six-package smoke-test commands. ## 4. Install Smoke Tests From A Pushed Branch Or `main` @@ -58,6 +64,8 @@ tmpdir="$(mktemp -d)" for path in \ skills/skill-context-keeper \ + skills/skill-subtask-context \ + skills/skill-context-packet \ skills/skill-phase-gate \ skills/skill-handoff-summary \ skills/skill-task-continuity @@ -77,6 +85,8 @@ tmpdir="$(mktemp -d)" for path in \ skills/skill-context-keeper \ + skills/skill-subtask-context \ + skills/skill-context-packet \ skills/skill-phase-gate \ skills/skill-handoff-summary \ skills/skill-task-continuity @@ -96,8 +106,8 @@ done ## 6. Changelog And Version Confirmation -- Confirm the next release is still `v0.6.1`. -- Confirm pinned install examples that reference a tag use `v0.6.1`. +- Confirm the next release tag is derived from `CHANGELOG.md` rather than an older placeholder. +- Confirm maintainer docs no longer hard-code a stale release target. - Confirm `CHANGELOG.md` is ready to ship with minimal or no editing. ## 7. Tag And GitHub Release @@ -106,8 +116,8 @@ done - Create the tag: ```bash -git tag v0.6.1 -git push origin v0.6.1 +git tag +git push origin ``` - Create the GitHub Release using the prepared release notes draft. @@ -121,6 +131,8 @@ tmpdir="$(mktemp -d)" for path in \ skills/skill-context-keeper \ + skills/skill-subtask-context \ + skills/skill-context-packet \ skills/skill-phase-gate \ skills/skill-handoff-summary \ skills/skill-task-continuity @@ -128,10 +140,10 @@ do python3 /scripts/install-skill-from-github.py \ --repo Golden-Promise/codex-skill-library \ --path "$path" \ - --ref v0.6.1 \ + --ref \ --dest "$tmpdir" done ``` - Confirm the tagged installs resolve to the expected package paths. -- Confirm the public GitHub release page points readers to the four published package directories under `skills/`. +- Confirm the public GitHub release page points readers to the six published continuity package directories under `skills/`. diff --git a/docs/release-checklist-long-task-suite.zh-CN.md b/docs/release-checklist-long-task-suite.zh-CN.md index 86d2654..3ec5bf6 100644 --- a/docs/release-checklist-long-task-suite.zh-CN.md +++ b/docs/release-checklist-long-task-suite.zh-CN.md @@ -7,13 +7,17 @@ ## 1. 发布前基本检查 - 确认工作树干净：`git status --short` -- 确认目标版本仍然是 `v0.6.1`；如果又插入了新的用户可见范围，先重新判断版本再打 tag。 +- 确认 [CHANGELOG.md](../CHANGELOG.md) 已反映真实发布范围，并据此推导下一个 `` - 重新检查仓库入口和索引页： - [README.md](../README.md) - [README.zh-CN.md](../README.zh-CN.md) - [skills/README.md](../skills/README.md) - [skills/README.zh-CN.md](../skills/README.zh-CN.md) -- 确认 [CHANGELOG.md](../CHANGELOG.md) 与本次发布范围一致，没有描述尚未完成的内容。 +- 重新检查面向 protocol 的维护文档： + - [docs/context-protocol-migration.md](context-protocol-migration.md) + - [docs/context-protocol-migration.zh-CN.md](context-protocol-migration.zh-CN.md) + - [docs/long-task-suite.md](long-task-suite.md) + - [docs/long-task-suite.zh-CN.md](long-task-suite.zh-CN.md) ## 2. 本地校验 @@ -40,14 +44,16 @@ python3 evals/run_evals.py ## 3. 文档与索引核对 -- 确认四个连续性包仍然能从根 README 和 `skills/` 索引页找到。 -- 确认四个包的职责仍然不重叠： - - `skill-context-keeper` = 只负责状态刷新 - - `skill-phase-gate` = 只负责检查点 - - `skill-handoff-summary` = 只负责交接摘要 - - `skill-task-continuity` = 只负责套件启动与组合 -- 确认各包 `README.md` 里的安装段落仍然指向公开发布路径 `skills//`。 -- 确认发布说明文档仍然链接到这份清单和连续性包的 smoke-test 命令。 +- 确认 6 个连续性包都能从根 README 和 `skills/` 索引页找到。 +- 确认各包职责仍然不重叠： + - `skill-context-keeper` = root-state refresh 和 compression + - `skill-subtask-context` = bounded child-task state + - `skill-context-packet` = minimum next-turn packet + - `skill-phase-gate` = optional checkpoint only + - `skill-handoff-summary` = root 或 subtask handoff only + - `skill-task-continuity` = suite bootstrap 和 routing only +- 确认各包 `README.md` 中的安装段落仍然指向公开发布路径 `skills//`。 +- 确认发布说明仍然链接到这份清单和 6 包 smoke-test 命令。 ## 4. 从已推送分支或 `main` 运行安装 Smoke Test @@ -58,6 +64,8 @@ tmpdir="$(mktemp -d)" for path in \ skills/skill-context-keeper \ + skills/skill-subtask-context \ + skills/skill-context-packet \ skills/skill-phase-gate \ skills/skill-handoff-summary \ skills/skill-task-continuity @@ -77,6 +85,8 @@ tmpdir="$(mktemp -d)" for path in \ skills/skill-context-keeper \ + skills/skill-subtask-context \ + skills/skill-context-packet \ skills/skill-phase-gate \ skills/skill-handoff-summary \ skills/skill-task-continuity @@ -96,8 +106,8 @@ done ## 6. 变更日志与版本确认 -- 确认下一次发布仍然是 `v0.6.1`。 -- 确认所有固定 tag 的安装示例都使用 `v0.6.1`。 +- 确认下一个发布 tag 是根据 `CHANGELOG.md` 推导出来的，而不是沿用旧占位版本。 +- 确认维护文档里已经没有过时的固定目标版本。 - 确认 `CHANGELOG.md` 已经达到“基本不用再改就能发”的状态。 ## 7. 打 Tag 与 GitHub Release @@ -106,8 +116,8 @@ done - 创建并推送 tag： ```bash -git tag v0.6.1 -git push origin v0.6.1 +git tag +git push origin ``` - 使用准备好的 release notes draft 创建 GitHub Release。 @@ -121,6 +131,8 @@ tmpdir="$(mktemp -d)" for path in \ skills/skill-context-keeper \ + skills/skill-subtask-context \ + skills/skill-context-packet \ skills/skill-phase-gate \ skills/skill-handoff-summary \ skills/skill-task-continuity @@ -128,10 +140,10 @@ do python3 /scripts/install-skill-from-github.py \ --repo Golden-Promise/codex-skill-library \ --path "$path" \ - --ref v0.6.1 \ + --ref \ --dest "$tmpdir" done ``` - 确认 tag 安装解析到预期的包路径。 -- 确认 GitHub Release 页面能把读者正确带到 `skills/` 下的四个已发布包。 +- 确认 GitHub Release 页面能把读者正确带到 `skills/` 下 6 个已发布连续性包。 diff --git a/docs/superpowers/plans/2026-03-26-context-protocol-foundation.md b/docs/superpowers/plans/2026-03-26-context-protocol-foundation.md new file mode 100644 index 0000000..246cc01 --- /dev/null +++ b/docs/superpowers/plans/2026-03-26-context-protocol-foundation.md @@ -0,0 +1,416 @@ +# Context Protocol Foundation 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:** Ship the first executable slice of the context protocol redesign by introducing the new repo starter layout, bootstrapping root/subtask state artifacts, and adding the two new atomic packages that own subtask state and context packets. + +**Architecture:** Extend `skill-task-continuity` from the current flat `.agent-state/` bootstrap into a layered repo workflow with `INDEX.md`, `root/`, `subtasks/`, and `archive/` semantics. Add `skill-subtask-context` and `skill-context-packet` as documentation-first atomic packages with their own assets, prompts, and contract tests. Keep existing packages compatible for now, and defer deeper refocusing of legacy package boundaries plus richer eval coverage to follow-on plans. + +**Tech Stack:** Markdown package docs, Python `bootstrap_suite.py`, Python `unittest`, repo templates under `skills/`, existing continuity package structure + +--- + +## Scope Note + +The approved design spec spans three coupled implementation slices: + +1. foundation layout + bootstrap + new atomic packages +2. legacy skill refocus around root vs subtask scope +3. workflow evals, migration docs, and release hardening + +This plan intentionally covers **Slice 1 only** so the result is coherent, bootstrappable, and testable before the broader refactor lands. + +## File Map + +### Existing Files To Modify + +- Modify: `skills/README.md` + - Add `skill-subtask-context` and `skill-context-packet` to the published package index and continuity picker. +- Modify: `skills/README.zh-CN.md` + - Mirror the new package index and routing guidance in Chinese. +- Modify: `skills/skill-task-continuity/SKILL.md` + - Update suite routing language to account for root state, subtask state, and packets. +- Modify: `skills/skill-task-continuity/README.md` + - Replace the flat starter-file explanation with the layered root/subtask layout and beginner mode. +- Modify: `skills/skill-task-continuity/README.zh-CN.md` + - Mirror the English layout and beginner-mode changes in Chinese. +- Modify: `skills/skill-task-continuity/references/composition-guide.md` + - Explain packet-first execution and when to create a subtask. +- Modify: `skills/skill-task-continuity/references/composition-guide.zh-CN.md` + - Mirror the English composition-guide changes in Chinese. +- Modify: `skills/skill-task-continuity/references/install-playbook.md` + - Document bootstrap output for `INDEX.md`, `root/`, `subtasks/`, and `archive/`. +- Modify: `skills/skill-task-continuity/references/install-playbook.zh-CN.md` + - Mirror the English install-playbook changes in Chinese. +- Modify: `skills/skill-task-continuity/assets/AGENTS.repo-template.md` + - Rework the repo template around `INDEX.md`, root packets, subtask packets, and compression flow. +- Modify: `skills/skill-task-continuity/scripts/bootstrap_suite.py` + - Replace the flat `TEMPLATE_MAP` with the layered bootstrap layout and starter directory creation. +- Modify: `skills/skill-task-continuity/tests/test_bootstrap_suite.py` + - Lock in the layered bootstrap output, duplicate-template mapping, and beginner-mode behavior. +- Modify: `skills/skill-task-continuity/tests/test_docs_contract.py` + - Assert the new package names, new layout, and packet-first wording appear in suite docs. + +### New Files To Create Under `skill-task-continuity` + +- Create: `skills/skill-task-continuity/assets/agent-state/INDEX.template.md` +- Create: `skills/skill-task-continuity/assets/agent-state/root/TASK_STATE.template.md` +- Create: `skills/skill-task-continuity/assets/agent-state/root/PACKET.template.md` +- Create: `skills/skill-task-continuity/assets/agent-state/root/DECISIONS.template.md` +- Create: `skills/skill-task-continuity/assets/agent-state/root/RUN_LOG.template.md` +- Create: `skills/skill-task-continuity/assets/agent-state/root/HANDOFF.template.md` +- Create: `skills/skill-task-continuity/assets/agent-state/subtasks/TASK_STATE.template.md` +- Create: `skills/skill-task-continuity/assets/agent-state/subtasks/PACKET.template.md` +- Create: `skills/skill-task-continuity/assets/agent-state/subtasks/HANDOFF.template.md` +- Create: `skills/skill-task-continuity/assets/agent-state/subtasks/RUN_LOG.template.md` + +### New `skill-subtask-context` Package + +- Create: `skills/skill-subtask-context/SKILL.md` +- Create: `skills/skill-subtask-context/README.md` +- Create: `skills/skill-subtask-context/README.zh-CN.md` +- Create: `skills/skill-subtask-context/agents/openai.yaml` +- Create: `skills/skill-subtask-context/assets/TASK_STATE.template.md` +- Create: `skills/skill-subtask-context/references/README.md` +- Create: `skills/skill-subtask-context/references/README.zh-CN.md` +- Create: `skills/skill-subtask-context/references/use-cases.md` +- Create: `skills/skill-subtask-context/references/use-cases.zh-CN.md` +- Create: `skills/skill-subtask-context/references/prompt-templates.en.md` +- Create: `skills/skill-subtask-context/references/prompt-templates.zh-CN.md` +- Create: `skills/skill-subtask-context/tests/test_package_contract.py` + +### New `skill-context-packet` Package + +- Create: `skills/skill-context-packet/SKILL.md` +- Create: `skills/skill-context-packet/README.md` +- Create: `skills/skill-context-packet/README.zh-CN.md` +- Create: `skills/skill-context-packet/agents/openai.yaml` +- Create: `skills/skill-context-packet/assets/PACKET.template.md` +- Create: `skills/skill-context-packet/references/README.md` +- Create: `skills/skill-context-packet/references/README.zh-CN.md` +- Create: `skills/skill-context-packet/references/use-cases.md` +- Create: `skills/skill-context-packet/references/use-cases.zh-CN.md` +- Create: `skills/skill-context-packet/references/prompt-templates.en.md` +- Create: `skills/skill-context-packet/references/prompt-templates.zh-CN.md` +- Create: `skills/skill-context-packet/tests/test_package_contract.py` + +## Approved Design Notes + +- Keep the current four packages installable during this slice; add the two new packages without deleting anything yet. +- Make `INDEX.md` the repo entry point, not `TASK_STATE.md`. +- Make packets the default injection object. +- Use beginner mode as a subset of the expanded layout, not a separate bootstrap system. +- Reuse the current `skill-context-keeper` task-state asset and `skill-handoff-summary` handoff asset where possible, but duplicate them into the suite assets for downstream bootstrap. +- Leave deep rewrites of `skill-context-keeper`, `skill-handoff-summary`, and `skill-phase-gate` to the follow-on legacy-refocus plan. + +## Out Of Scope For This Plan + +- Rewriting legacy package prompts around root-vs-subtask scope +- Expanding `evals/cases.csv` for packet/subtask/compression scenarios +- Adding archive automation beyond bootstrap directory creation and documented compression flow +- Renaming or retiring legacy skills + +### Task 1: Add Failing Bootstrap And Documentation Contracts + +**Files:** +- Modify: `skills/skill-task-continuity/tests/test_bootstrap_suite.py` +- Modify: `skills/skill-task-continuity/tests/test_docs_contract.py` +- Test: `skills/skill-task-continuity/tests/test_bootstrap_suite.py` +- Test: `skills/skill-task-continuity/tests/test_docs_contract.py` + +- [ ] **Step 1: Extend the bootstrap tests to describe the new layered output** + +Add failing assertions for: +- `.agent-state/INDEX.md` +- `root/TASK_STATE.md`, `root/PACKET.md`, `root/HANDOFF.md` +- `subtasks/` starter structure or documented empty-directory behavior +- template duplication between suite assets and the relevant atomic package assets +- preservation of existing files without `--force` + +- [ ] **Step 2: Extend the docs contract tests to cover the new package topology** + +Add failing assertions that suite docs now mention: +- `skill-subtask-context` +- `skill-context-packet` +- `INDEX.md` +- root/subtask packet-first workflow +- beginner mode vs expanded mode + +- [ ] **Step 3: Run the two test modules to verify they fail** + +Run: +```bash +cd /home/jn/projects/codex/codex-skill-library/.worktrees/continuity-maintenance +python3 -m unittest discover -s skills/skill-task-continuity/tests -p 'test_bootstrap_suite.py' -v +python3 -m unittest discover -s skills/skill-task-continuity/tests -p 'test_docs_contract.py' -v +``` +Expected: FAIL because the current suite still describes the flat layout and lacks the new package docs. + +- [ ] **Step 4: Commit the red-test checkpoint if you want an explicit TDD breadcrumb** + +```bash +git add skills/skill-task-continuity/tests/test_bootstrap_suite.py skills/skill-task-continuity/tests/test_docs_contract.py +git commit -m "test: add context protocol foundation contracts" +``` + +### Task 2: Implement The Layered Bootstrap Layout In `skill-task-continuity` + +**Files:** +- Modify: `skills/skill-task-continuity/SKILL.md` +- Modify: `skills/skill-task-continuity/README.md` +- Modify: `skills/skill-task-continuity/README.zh-CN.md` +- Modify: `skills/skill-task-continuity/references/composition-guide.md` +- Modify: `skills/skill-task-continuity/references/composition-guide.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/assets/AGENTS.repo-template.md` +- Modify: `skills/skill-task-continuity/scripts/bootstrap_suite.py` +- Create: `skills/skill-task-continuity/assets/agent-state/INDEX.template.md` +- Create: `skills/skill-task-continuity/assets/agent-state/root/TASK_STATE.template.md` +- Create: `skills/skill-task-continuity/assets/agent-state/root/PACKET.template.md` +- Create: `skills/skill-task-continuity/assets/agent-state/root/DECISIONS.template.md` +- Create: `skills/skill-task-continuity/assets/agent-state/root/RUN_LOG.template.md` +- Create: `skills/skill-task-continuity/assets/agent-state/root/HANDOFF.template.md` +- Create: `skills/skill-task-continuity/assets/agent-state/subtasks/TASK_STATE.template.md` +- Create: `skills/skill-task-continuity/assets/agent-state/subtasks/PACKET.template.md` +- Create: `skills/skill-task-continuity/assets/agent-state/subtasks/HANDOFF.template.md` +- Create: `skills/skill-task-continuity/assets/agent-state/subtasks/RUN_LOG.template.md` +- Test: `skills/skill-task-continuity/tests/test_bootstrap_suite.py` +- Test: `skills/skill-task-continuity/tests/test_docs_contract.py` + +- [ ] **Step 1: Create the new suite starter templates** + +Author the layered templates so: +- `INDEX.template.md` routes into root or subtask packets +- root templates model durable top-level state +- subtask templates model local state and local packet execution +- handoff templates are consistent with the existing continuation contract + +- [ ] **Step 2: Replace the flat bootstrap mapping with the layered layout** + +Update `bootstrap_suite.py` so it: +- copies the new root and subtask starter files +- creates the missing archive directories +- preserves existing files unless `--force` +- continues refusing the public library root + +- [ ] **Step 3: Rewrite suite docs around beginner mode and expanded mode** + +Update package docs so they explain: +- beginner mode = `INDEX.md` + `root/` only +- expanded mode = `subtasks/` and `archive/` +- packets are the default injection surface +- root task and subtask are distinct context owners + +- [ ] **Step 4: Re-run the two task-continuity test modules** + +Run: +```bash +cd /home/jn/projects/codex/codex-skill-library/.worktrees/continuity-maintenance +python3 -m unittest discover -s skills/skill-task-continuity/tests -p 'test_bootstrap_suite.py' -v +python3 -m unittest discover -s skills/skill-task-continuity/tests -p 'test_docs_contract.py' -v +``` +Expected: PASS + +- [ ] **Step 5: Commit the layered bootstrap slice** + +```bash +git add skills/skill-task-continuity/SKILL.md skills/skill-task-continuity/README.md skills/skill-task-continuity/README.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/references/install-playbook.md skills/skill-task-continuity/references/install-playbook.zh-CN.md skills/skill-task-continuity/assets/AGENTS.repo-template.md skills/skill-task-continuity/assets/agent-state/INDEX.template.md skills/skill-task-continuity/assets/agent-state/root/TASK_STATE.template.md skills/skill-task-continuity/assets/agent-state/root/PACKET.template.md skills/skill-task-continuity/assets/agent-state/root/DECISIONS.template.md skills/skill-task-continuity/assets/agent-state/root/RUN_LOG.template.md skills/skill-task-continuity/assets/agent-state/root/HANDOFF.template.md skills/skill-task-continuity/assets/agent-state/subtasks/TASK_STATE.template.md skills/skill-task-continuity/assets/agent-state/subtasks/PACKET.template.md skills/skill-task-continuity/assets/agent-state/subtasks/HANDOFF.template.md skills/skill-task-continuity/assets/agent-state/subtasks/RUN_LOG.template.md skills/skill-task-continuity/scripts/bootstrap_suite.py skills/skill-task-continuity/tests/test_bootstrap_suite.py skills/skill-task-continuity/tests/test_docs_contract.py +git commit -m "feat: bootstrap the context protocol layout" +``` + +### Task 3: Add The `skill-subtask-context` Package + +**Files:** +- Create: `skills/skill-subtask-context/SKILL.md` +- Create: `skills/skill-subtask-context/README.md` +- Create: `skills/skill-subtask-context/README.zh-CN.md` +- Create: `skills/skill-subtask-context/agents/openai.yaml` +- Create: `skills/skill-subtask-context/assets/TASK_STATE.template.md` +- Create: `skills/skill-subtask-context/references/README.md` +- Create: `skills/skill-subtask-context/references/README.zh-CN.md` +- Create: `skills/skill-subtask-context/references/use-cases.md` +- Create: `skills/skill-subtask-context/references/use-cases.zh-CN.md` +- Create: `skills/skill-subtask-context/references/prompt-templates.en.md` +- Create: `skills/skill-subtask-context/references/prompt-templates.zh-CN.md` +- Create: `skills/skill-subtask-context/tests/test_package_contract.py` +- Test: `skills/skill-subtask-context/tests/test_package_contract.py` + +- [ ] **Step 1: Write the failing package contract** + +Add tests that require: +- the new package files to exist +- README fast-entry sections in both languages +- use-case and prompt-template references in both languages +- a subtask-state asset with the required headings +- direct natural-language invocation wording + +- [ ] **Step 2: Run the new test module to verify it fails** + +Run: +```bash +cd /home/jn/projects/codex/codex-skill-library/.worktrees/continuity-maintenance +python3 -m unittest discover -s skills/skill-subtask-context/tests -p 'test_package_contract.py' -v +``` +Expected: FAIL because the package does not exist yet. + +- [ ] **Step 3: Author the package** + +Implement: +- the narrow package boundary around subtask creation, refresh, closure, and local state ownership +- a subtask state template aligned to the approved spec +- bilingual README and reference docs consistent with existing package style + +- [ ] **Step 4: Re-run the package test** + +Run the same `python3 -m unittest discover ...` command from Step 2. +Expected: PASS + +- [ ] **Step 5: Commit the new package** + +```bash +git add skills/skill-subtask-context +git commit -m "feat: add subtask context skill" +``` + +### Task 4: Add The `skill-context-packet` Package + +**Files:** +- Create: `skills/skill-context-packet/SKILL.md` +- Create: `skills/skill-context-packet/README.md` +- Create: `skills/skill-context-packet/README.zh-CN.md` +- Create: `skills/skill-context-packet/agents/openai.yaml` +- Create: `skills/skill-context-packet/assets/PACKET.template.md` +- Create: `skills/skill-context-packet/references/README.md` +- Create: `skills/skill-context-packet/references/README.zh-CN.md` +- Create: `skills/skill-context-packet/references/use-cases.md` +- Create: `skills/skill-context-packet/references/use-cases.zh-CN.md` +- Create: `skills/skill-context-packet/references/prompt-templates.en.md` +- Create: `skills/skill-context-packet/references/prompt-templates.zh-CN.md` +- Create: `skills/skill-context-packet/tests/test_package_contract.py` +- Test: `skills/skill-context-packet/tests/test_package_contract.py` + +- [ ] **Step 1: Write the failing package contract** + +Add tests that require: +- package metadata and docs to exist +- README fast-entry sections and direct invocation wording +- a packet template with explicit objective, constraints, verified facts, active risks, exact next action, and file-reference sections +- bilingual reference index and prompt-template coverage + +- [ ] **Step 2: Run the new test module to verify it fails** + +Run: +```bash +cd /home/jn/projects/codex/codex-skill-library/.worktrees/continuity-maintenance +python3 -m unittest discover -s skills/skill-context-packet/tests -p 'test_package_contract.py' -v +``` +Expected: FAIL because the package does not exist yet. + +- [ ] **Step 3: Author the package** + +Implement: +- the boundary around building or refreshing the minimum context packet for the next action +- a generic packet template usable for root and subtask packet duplication +- bilingual docs aligned with the current package conventions + +- [ ] **Step 4: Re-run the package test** + +Run the same `python3 -m unittest discover ...` command from Step 2. +Expected: PASS + +- [ ] **Step 5: Commit the new package** + +```bash +git add skills/skill-context-packet +git commit -m "feat: add context packet skill" +``` + +### Task 5: Update The Published Skill Index And Suite Routing + +**Files:** +- Modify: `skills/README.md` +- Modify: `skills/README.zh-CN.md` +- Modify: `skills/skill-task-continuity/tests/test_docs_contract.py` +- Test: `skills/skill-task-continuity/tests/test_docs_contract.py` + +- [ ] **Step 1: Update the top-level skill index** + +Add: +- the two new packages in the published package table +- quick-picker wording that differentiates root-state refresh, subtask work, and packet generation + +- [ ] **Step 2: Re-run the docs contract** + +Run: +```bash +cd /home/jn/projects/codex/codex-skill-library/.worktrees/continuity-maintenance +python3 -m unittest discover -s skills/skill-task-continuity/tests -p 'test_docs_contract.py' -v +``` +Expected: PASS + +- [ ] **Step 3: Commit the routing update** + +```bash +git add skills/README.md skills/README.zh-CN.md skills/skill-task-continuity/tests/test_docs_contract.py +git commit -m "docs: route continuity users to the new context packages" +``` + +### Task 6: Run Foundation Verification And Record The Plan + +**Files:** +- Verify only: `skills/skill-task-continuity/tests/test_bootstrap_suite.py` +- Verify only: `skills/skill-task-continuity/tests/test_docs_contract.py` +- Verify only: `skills/skill-subtask-context/tests/test_package_contract.py` +- Verify only: `skills/skill-context-packet/tests/test_package_contract.py` +- Verify only: `skills/skill-context-keeper/tests/test_package_contract.py` +- Verify only: `skills/skill-handoff-summary/tests/test_package_contract.py` +- Verify only: `evals/test_run_evals.py` +- Modify: `docs/superpowers/plans/2026-03-26-context-protocol-foundation.md` + +- [ ] **Step 1: Run the foundation package tests** + +Run: +```bash +cd /home/jn/projects/codex/codex-skill-library/.worktrees/continuity-maintenance +python3 -m unittest discover -s skills/skill-task-continuity/tests -p 'test_*.py' -v +python3 -m unittest discover -s skills/skill-subtask-context/tests -p 'test_*.py' -v +python3 -m unittest discover -s skills/skill-context-packet/tests -p 'test_*.py' -v +python3 -m unittest discover -s skills/skill-context-keeper/tests -p 'test_*.py' -v +python3 -m unittest discover -s skills/skill-handoff-summary/tests -p 'test_*.py' -v +``` +Expected: PASS + +- [ ] **Step 2: Run eval unit tests to catch continuity-routing regressions** + +Run: +```bash +cd /home/jn/projects/codex/codex-skill-library/.worktrees/continuity-maintenance +python3 -m unittest discover -s evals -p 'test_*.py' -v +``` +Expected: PASS + +- [ ] **Step 3: Inspect git state** + +Run: +```bash +git -C /home/jn/projects/codex/codex-skill-library/.worktrees/continuity-maintenance status --short +git -C /home/jn/projects/codex/codex-skill-library/.worktrees/continuity-maintenance diff --stat +``` +Expected: only the planned foundation files are changed + +- [ ] **Step 4: Commit the plan document after execution notes are current** + +```bash +git add docs/superpowers/plans/2026-03-26-context-protocol-foundation.md +git commit -m "docs: record context protocol foundation plan" +``` + +## Follow-On Plans + +After this foundation slice lands, write separate implementation plans for: + +1. **Legacy Skill Refocus** + Rework `skill-context-keeper`, `skill-handoff-summary`, and `skill-phase-gate` around the root/subtask protocol. +2. **Workflow Evals And Migration** + Add scenario evals for packets, subtasks, compression, and downstream migration guidance. diff --git a/docs/superpowers/plans/2026-03-27-context-protocol-legacy-refocus.md b/docs/superpowers/plans/2026-03-27-context-protocol-legacy-refocus.md new file mode 100644 index 0000000..f5c4a70 --- /dev/null +++ b/docs/superpowers/plans/2026-03-27-context-protocol-legacy-refocus.md @@ -0,0 +1,331 @@ +# Context Protocol Legacy Refocus 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:** Refocus the legacy continuity packages so `skill-context-keeper`, `skill-handoff-summary`, and `skill-phase-gate` align with the new context-protocol model without deleting stable install paths. + +**Architecture:** Use contract-first updates to the three legacy packages, then rewrite their docs, prompts, and shared templates around root-state refresh, standardized root/subtask handoffs, and optional operational checkpoints. Keep `skill-task-continuity` as the suite router and synchronize its duplicated assets anywhere the atomic packages remain the source of truth. + +**Tech Stack:** Markdown skill docs, template assets under `skills/`, Python `unittest`, existing continuity package layout + +--- + +## Scope Note + +This plan covers **Slice 2 only** from the approved design: + +1. refocus legacy packages around root vs subtask scope +2. keep the newly added protocol packages installable +3. leave eval expansion, migration docs, and release hardening to the follow-on slice + +This plan assumes the current foundation slice in this worktree is the baseline. +If you want clean commit boundaries, commit the foundation slice before executing this plan. + +## File Map + +### Existing Files To Modify + +- Modify: `skills/README.md` + - Update the published package blurbs so legacy roles match the new protocol model. +- Modify: `skills/README.zh-CN.md` + - Mirror the revised package blurbs in Chinese. +- Modify: `skills/skill-context-keeper/SKILL.md` + - Narrow the package to root-state refresh and compression guidance. +- Modify: `skills/skill-context-keeper/README.md` + - Change the default artifact path to `.agent-state/root/TASK_STATE.md` and explain the compression boundary. +- Modify: `skills/skill-context-keeper/README.zh-CN.md` + - Mirror the English root-state and compression guidance. +- Modify: `skills/skill-context-keeper/agents/openai.yaml` + - Align the default prompt with root-state refresh only. +- Modify: `skills/skill-context-keeper/assets/TASK_STATE.template.md` + - Add an explicit compression / archive section for root-state maintenance. +- Modify: `skills/skill-context-keeper/references/use-cases.md` + - Shift examples to root-state refresh and compression. +- Modify: `skills/skill-context-keeper/references/use-cases.zh-CN.md` + - Mirror the English use-case changes in Chinese. +- Modify: `skills/skill-context-keeper/references/prompt-templates.en.md` + - Update prompt wording for `.agent-state/root/TASK_STATE.md` and archive-minded refreshes. +- Modify: `skills/skill-context-keeper/references/prompt-templates.zh-CN.md` + - Mirror the English prompt changes in Chinese. +- Modify: `skills/skill-context-keeper/tests/test_package_contract.py` + - Assert root-state paths and compression-specific package boundaries. +- Modify: `skills/skill-handoff-summary/SKILL.md` + - Refocus the package on a standard handoff contract usable for root or subtask scope. +- Modify: `skills/skill-handoff-summary/README.md` + - Replace the single flat handoff path with root/subtask handoff guidance. +- Modify: `skills/skill-handoff-summary/README.zh-CN.md` + - Mirror the English root/subtask handoff guidance in Chinese. +- Modify: `skills/skill-handoff-summary/agents/openai.yaml` + - Align the default prompt with root/subtask handoff generation. +- Modify: `skills/skill-handoff-summary/assets/HANDOFF.template.md` + - Make the template path-neutral enough to serve both root and subtask handoffs. +- Modify: `skills/skill-handoff-summary/references/use-cases.md` + - Update trigger examples so the package works for root and subtask pauses. +- Modify: `skills/skill-handoff-summary/references/use-cases.zh-CN.md` + - Mirror the English use-case changes in Chinese. +- Modify: `skills/skill-handoff-summary/references/prompt-templates.en.md` + - Replace flat-path prompts with root/subtask handoff prompts. +- Modify: `skills/skill-handoff-summary/references/prompt-templates.zh-CN.md` + - Mirror the English prompt changes in Chinese. +- Modify: `skills/skill-handoff-summary/tests/test_package_contract.py` + - Assert the generalized handoff contract and root/subtask wording. +- Modify: `skills/skill-phase-gate/SKILL.md` + - Reframe the package as an optional operational checkpoint, not a continuity centerpiece. +- Modify: `skills/skill-phase-gate/README.md` + - Clarify that the package is for risky edits, not root-state refresh or packet management. +- Modify: `skills/skill-phase-gate/README.zh-CN.md` + - Mirror the English boundary changes in Chinese. +- Modify: `skills/skill-phase-gate/agents/openai.yaml` + - Align the default prompt with optional checkpoint usage. +- Modify: `skills/skill-phase-gate/references/use-cases.md` + - Tighten positive/negative triggers around risky edits only. +- Modify: `skills/skill-phase-gate/references/use-cases.zh-CN.md` + - Mirror the English use-case changes in Chinese. +- Modify: `skills/skill-phase-gate/references/prompt-templates.en.md` + - Remove stale continuity-center wording and keep packet/root-state out of scope. +- Modify: `skills/skill-phase-gate/references/prompt-templates.zh-CN.md` + - Mirror the English prompt changes in Chinese. +- Modify: `skills/skill-phase-gate/tests/test_package_contract.py` + - Assert the new “optional checkpoint only” boundary. +- Modify: `skills/skill-task-continuity/assets/agent-state/root/TASK_STATE.template.md` + - Keep the suite duplicate in sync with the atomic root-state template. +- Modify: `skills/skill-task-continuity/assets/agent-state/root/HANDOFF.template.md` + - Keep the suite duplicate in sync with the atomic handoff template. +- Modify: `skills/skill-task-continuity/assets/agent-state/subtasks/HANDOFF.template.md` + - Reuse the standardized handoff contract for subtask scope. +- Modify: `skills/skill-task-continuity/tests/test_bootstrap_suite.py` + - Extend duplicate-template checks to cover the standardized handoff contract. + +## Out Of Scope For This Plan + +- Expanding `evals/cases.csv` or adding workflow eval runners +- Writing downstream migration guides or release notes +- Renaming or retiring the older package names +- Adding archive automation beyond doc and template guidance + +### Task 1: Add Failing Legacy-Refocus Contracts + +**Files:** +- Modify: `skills/skill-context-keeper/tests/test_package_contract.py` +- Modify: `skills/skill-handoff-summary/tests/test_package_contract.py` +- Modify: `skills/skill-phase-gate/tests/test_package_contract.py` +- Modify: `skills/skill-task-continuity/tests/test_bootstrap_suite.py` +- Test: `skills/skill-context-keeper/tests/test_package_contract.py` +- Test: `skills/skill-handoff-summary/tests/test_package_contract.py` +- Test: `skills/skill-phase-gate/tests/test_package_contract.py` +- Test: `skills/skill-task-continuity/tests/test_bootstrap_suite.py` + +- [ ] **Step 1: Extend the context-keeper contract around root-state ownership** + +Add failing assertions for: +- `.agent-state/root/TASK_STATE.md` instead of the old flat path +- explicit wording that the package owns root-state refresh and compression +- a new template heading such as `## Compression / Archive Notes` + +- [ ] **Step 2: Extend the handoff-summary contract around root/subtask reuse** + +Add failing assertions for: +- root and subtask handoff wording in the README and prompt templates +- a path-neutral resume prompt in the atomic handoff template +- package boundary wording that rules out whole-project docs and state refresh + +- [ ] **Step 3: Extend the phase-gate contract around optional checkpoint-only usage** + +Add failing assertions for: +- “optional operational checkpoint” wording +- explicit rejection of root-state refresh, packet compression, and suite bootstrap usage +- related-skill routing to the newer packet and subtask packages + +- [ ] **Step 4: Extend the suite duplication test for the standardized handoff template** + +Require both: +- `assets/agent-state/root/HANDOFF.template.md` +- `assets/agent-state/subtasks/HANDOFF.template.md` + +to match the atomic `skill-handoff-summary` handoff asset exactly. + +- [ ] **Step 5: Run the legacy contract modules to verify they fail** + +Run: +```bash +cd /home/jn/projects/codex/codex-skill-library/.worktrees/continuity-maintenance +python3 -m unittest discover -s skills/skill-context-keeper/tests -p 'test_package_contract.py' -v +python3 -m unittest discover -s skills/skill-handoff-summary/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-task-continuity/tests -p 'test_bootstrap_suite.py' -v +``` +Expected: FAIL because the legacy packages still describe the old flat paths and narrower handoff contract. + +### Task 2: Refocus `skill-context-keeper` On Root-State Refresh And Compression + +**Files:** +- Modify: `skills/skill-context-keeper/SKILL.md` +- Modify: `skills/skill-context-keeper/README.md` +- Modify: `skills/skill-context-keeper/README.zh-CN.md` +- Modify: `skills/skill-context-keeper/agents/openai.yaml` +- Modify: `skills/skill-context-keeper/assets/TASK_STATE.template.md` +- Modify: `skills/skill-context-keeper/references/use-cases.md` +- Modify: `skills/skill-context-keeper/references/use-cases.zh-CN.md` +- Modify: `skills/skill-context-keeper/references/prompt-templates.en.md` +- Modify: `skills/skill-context-keeper/references/prompt-templates.zh-CN.md` +- Modify: `skills/skill-context-keeper/tests/test_package_contract.py` +- Modify: `skills/skill-task-continuity/assets/agent-state/root/TASK_STATE.template.md` +- Test: `skills/skill-context-keeper/tests/test_package_contract.py` +- Test: `skills/skill-task-continuity/tests/test_bootstrap_suite.py` + +- [ ] **Step 1: Update the root task-state asset and its suite duplicate** + +Add the compression-specific section to both task-state templates and keep their contents byte-for-byte identical. + +- [ ] **Step 2: Rewrite the package boundary and examples** + +Update SKILL, README, prompt templates, and use cases so they: +- point to `.agent-state/root/TASK_STATE.md` +- describe root-state refresh and compression only +- route subtask work to `skill-subtask-context` +- route minimal injection work to `skill-context-packet` + +- [ ] **Step 3: Re-run the keeper and suite tests** + +Run: +```bash +cd /home/jn/projects/codex/codex-skill-library/.worktrees/continuity-maintenance +python3 -m unittest discover -s skills/skill-context-keeper/tests -p 'test_package_contract.py' -v +python3 -m unittest discover -s skills/skill-task-continuity/tests -p 'test_bootstrap_suite.py' -v +``` +Expected: PASS + +- [ ] **Step 4: Commit the root-state refocus slice** + +```bash +git add skills/skill-context-keeper/SKILL.md skills/skill-context-keeper/README.md skills/skill-context-keeper/README.zh-CN.md skills/skill-context-keeper/agents/openai.yaml skills/skill-context-keeper/assets/TASK_STATE.template.md skills/skill-context-keeper/references/use-cases.md skills/skill-context-keeper/references/use-cases.zh-CN.md skills/skill-context-keeper/references/prompt-templates.en.md skills/skill-context-keeper/references/prompt-templates.zh-CN.md skills/skill-context-keeper/tests/test_package_contract.py skills/skill-task-continuity/assets/agent-state/root/TASK_STATE.template.md +git commit -m "feat: refocus context keeper on root state" +``` + +### Task 3: Refocus `skill-handoff-summary` On A Standard Root/Subtask Contract + +**Files:** +- Modify: `skills/skill-handoff-summary/SKILL.md` +- Modify: `skills/skill-handoff-summary/README.md` +- Modify: `skills/skill-handoff-summary/README.zh-CN.md` +- Modify: `skills/skill-handoff-summary/agents/openai.yaml` +- Modify: `skills/skill-handoff-summary/assets/HANDOFF.template.md` +- Modify: `skills/skill-handoff-summary/references/use-cases.md` +- Modify: `skills/skill-handoff-summary/references/use-cases.zh-CN.md` +- Modify: `skills/skill-handoff-summary/references/prompt-templates.en.md` +- Modify: `skills/skill-handoff-summary/references/prompt-templates.zh-CN.md` +- Modify: `skills/skill-handoff-summary/tests/test_package_contract.py` +- Modify: `skills/skill-task-continuity/assets/agent-state/root/HANDOFF.template.md` +- Modify: `skills/skill-task-continuity/assets/agent-state/subtasks/HANDOFF.template.md` +- Modify: `skills/skill-task-continuity/tests/test_bootstrap_suite.py` +- Test: `skills/skill-handoff-summary/tests/test_package_contract.py` +- Test: `skills/skill-task-continuity/tests/test_bootstrap_suite.py` + +- [ ] **Step 1: Rewrite the atomic handoff template to be reusable** + +Change the handoff template and its resume prompt so it can serve both root and subtask scopes without hard-coding only one flat downstream path. + +- [ ] **Step 2: Copy the new handoff template into the suite duplicates** + +Make both suite handoff templates match the atomic asset exactly so the bootstrap helper continues to have one source of truth. + +- [ ] **Step 3: Rewrite docs and prompts around root/subtask handoffs** + +Update SKILL, README, prompt templates, and use cases so they: +- mention `.agent-state/root/HANDOFF.md` and `.agent-state/subtasks//HANDOFF.md` +- keep the package continuation-oriented +- avoid state-refresh or workflow-gate ownership + +- [ ] **Step 4: Re-run the handoff and suite tests** + +Run: +```bash +cd /home/jn/projects/codex/codex-skill-library/.worktrees/continuity-maintenance +python3 -m unittest discover -s skills/skill-handoff-summary/tests -p 'test_package_contract.py' -v +python3 -m unittest discover -s skills/skill-task-continuity/tests -p 'test_bootstrap_suite.py' -v +``` +Expected: PASS + +- [ ] **Step 5: Commit the handoff refocus slice** + +```bash +git add skills/skill-handoff-summary/SKILL.md skills/skill-handoff-summary/README.md skills/skill-handoff-summary/README.zh-CN.md skills/skill-handoff-summary/agents/openai.yaml skills/skill-handoff-summary/assets/HANDOFF.template.md skills/skill-handoff-summary/references/use-cases.md skills/skill-handoff-summary/references/use-cases.zh-CN.md skills/skill-handoff-summary/references/prompt-templates.en.md skills/skill-handoff-summary/references/prompt-templates.zh-CN.md skills/skill-handoff-summary/tests/test_package_contract.py skills/skill-task-continuity/assets/agent-state/root/HANDOFF.template.md skills/skill-task-continuity/assets/agent-state/subtasks/HANDOFF.template.md skills/skill-task-continuity/tests/test_bootstrap_suite.py +git commit -m "feat: standardize handoff scope" +``` + +### Task 4: Refocus `skill-phase-gate` As An Optional Operational Checkpoint + +**Files:** +- Modify: `skills/skill-phase-gate/SKILL.md` +- Modify: `skills/skill-phase-gate/README.md` +- Modify: `skills/skill-phase-gate/README.zh-CN.md` +- Modify: `skills/skill-phase-gate/agents/openai.yaml` +- Modify: `skills/skill-phase-gate/references/use-cases.md` +- Modify: `skills/skill-phase-gate/references/use-cases.zh-CN.md` +- Modify: `skills/skill-phase-gate/references/prompt-templates.en.md` +- Modify: `skills/skill-phase-gate/references/prompt-templates.zh-CN.md` +- Modify: `skills/skill-phase-gate/tests/test_package_contract.py` +- Test: `skills/skill-phase-gate/tests/test_package_contract.py` + +- [ ] **Step 1: Rewrite the package boundary in tests and docs** + +Make the package explicitly about risky edits and meaningful checkpoints, not context refresh, packet compression, or suite coordination. + +- [ ] **Step 2: Update related-skill routing** + +Point stale-state requests to `skill-context-keeper`, packet requests to `skill-context-packet`, and subtask-local state requests to `skill-subtask-context`. + +- [ ] **Step 3: Re-run the phase-gate tests** + +Run: +```bash +cd /home/jn/projects/codex/codex-skill-library/.worktrees/continuity-maintenance +python3 -m unittest discover -s skills/skill-phase-gate/tests -p 'test_package_contract.py' -v +``` +Expected: PASS + +- [ ] **Step 4: Commit the checkpoint-only refocus slice** + +```bash +git add skills/skill-phase-gate/SKILL.md skills/skill-phase-gate/README.md skills/skill-phase-gate/README.zh-CN.md skills/skill-phase-gate/agents/openai.yaml skills/skill-phase-gate/references/use-cases.md skills/skill-phase-gate/references/use-cases.zh-CN.md skills/skill-phase-gate/references/prompt-templates.en.md skills/skill-phase-gate/references/prompt-templates.zh-CN.md skills/skill-phase-gate/tests/test_package_contract.py +git commit -m "feat: refocus phase gate boundaries" +``` + +### Task 5: Sync Top-Level Package Index And Verify The Slice + +**Files:** +- Modify: `skills/README.md` +- Modify: `skills/README.zh-CN.md` +- Test: `skills/skill-context-keeper/tests/test_package_contract.py` +- Test: `skills/skill-handoff-summary/tests/test_package_contract.py` +- Test: `skills/skill-phase-gate/tests/test_package_contract.py` +- Test: `skills/skill-task-continuity/tests/test_bootstrap_suite.py` + +- [ ] **Step 1: Update the published package blurbs** + +Change the top-level skill index so it describes: +- `skill-context-keeper` as root-state refresh and compression +- `skill-handoff-summary` as a root/subtask continuation contract +- `skill-phase-gate` as an optional risky-change checkpoint + +- [ ] **Step 2: Run the verification set** + +Run: +```bash +cd /home/jn/projects/codex/codex-skill-library/.worktrees/continuity-maintenance +git diff --check +python3 -m unittest discover -s skills/skill-context-keeper/tests -p 'test_package_contract.py' -v +python3 -m unittest discover -s skills/skill-handoff-summary/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-task-continuity/tests -p 'test_bootstrap_suite.py' -v +python3 -m unittest discover -s skills/skill-subtask-context/tests -p 'test_package_contract.py' -v +python3 -m unittest discover -s skills/skill-context-packet/tests -p 'test_package_contract.py' -v +``` +Expected: PASS with a clean diff check. + +- [ ] **Step 3: Commit the legacy-refocus slice** + +```bash +git add skills/README.md skills/README.zh-CN.md +git commit -m "feat: refocus legacy continuity skills" +``` diff --git a/docs/superpowers/plans/2026-03-27-context-protocol-validation-and-release-hardening.md b/docs/superpowers/plans/2026-03-27-context-protocol-validation-and-release-hardening.md new file mode 100644 index 0000000..4d02848 --- /dev/null +++ b/docs/superpowers/plans/2026-03-27-context-protocol-validation-and-release-hardening.md @@ -0,0 +1,335 @@ +# Context Protocol Validation And Release Hardening 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 context-protocol redesign shippable by expanding static workflow evals, publishing a repo-level migration guide, and hardening the release docs around the new six-package continuity workflow. + +**Architecture:** Treat the current foundation and legacy-refocus slices as the baseline, then update the repository-facing validation layer to understand root state, subtask state, and packet-sized context. Publish a dedicated migration guide plus refreshed suite overview docs so readers can move from the legacy four-package mental model to the new protocol model, and finish by tightening publishing and release-checklist docs so maintainers validate and ship the correct surface area. + +**Tech Stack:** Markdown docs, CSV seed matrix, Python `evals/run_evals.py`, Python `unittest`, repository release docs under `docs/` + +--- + +## Scope Note + +This plan covers **Slice 3 only** from the approved design: + +1. workflow eval expansion +2. migration and overview docs for the context protocol +3. release and publishing hardening + +This plan assumes the following baseline has already landed in the worktree: + +- `cfe3581` `feat: add context protocol foundation` +- `101fde0` `feat: refocus legacy continuity skills` + +## File Map + +### Existing Files To Modify + +- Modify: `README.md` + - Publish the two new continuity packages from the repo root and link the migration guide. +- Modify: `README.zh-CN.md` + - Mirror the English root-index and migration-guide changes in Chinese. +- Modify: `CHANGELOG.md` + - Record the context-protocol rollout slices and replace stale release-target wording with release-scope-driven guidance. +- Modify: `docs/long-task-suite.md` + - Rewrite the suite overview around the six-package protocol model and the new evaluation matrix. +- Modify: `docs/long-task-suite.zh-CN.md` + - Mirror the English suite-overview and matrix changes in Chinese. +- Modify: `docs/publishing.md` + - Replace the old four-package continuity publication flow with the six-package protocol flow and release-target placeholders. +- Modify: `docs/publishing.zh-CN.md` + - Mirror the English publishing-guide changes in Chinese. +- Modify: `docs/release-checklist-long-task-suite.md` + - Update the checklist, smoke-test loops, and release-verification language for the protocol model. +- Modify: `docs/release-checklist-long-task-suite.zh-CN.md` + - Mirror the English checklist changes in Chinese. +- Modify: `evals/README.md` + - Explain the protocol-aware seed matrix, new package coverage, and updated artifact tokens. +- Modify: `evals/cases.csv` + - Replace the old eight-case matrix with the protocol-era workflow cases and normalized artifact/event tokens. +- Modify: `evals/run_evals.py` + - Update package rules, artifact mapping, and workflow checks for `skill-subtask-context`, `skill-context-packet`, and the root/subtask layout. +- Modify: `evals/test_run_evals.py` + - Lock in the new seed matrix, package rules, and runner behavior. + +### New Files To Create + +- Create: `docs/context-protocol-migration.md` + - Explain how existing users should move from the legacy four-package continuity mental model to the root/subtask/packet protocol. +- Create: `docs/context-protocol-migration.zh-CN.md` + - Mirror the English migration guide in Chinese. + +## Approved Design Notes + +- Keep the static eval harness repo-driven; do not add live model execution in this slice. +- Treat the migration guide as a compatibility document for existing users, not as a new product spec. +- Make `docs/long-task-suite.*` reflect the current six-package topology instead of the withdrawn four-package framing. +- Remove hard-coded “current release target is `v0.6.1`” wording from maintainer docs; release docs should derive the next tag from actual release scope. +- Keep package install paths stable; this slice documents migration and release posture, not package renames. + +## Out Of Scope For This Plan + +- Renaming or deleting legacy packages +- Adding automatic repository migration scripts +- Adding platform-specific telemetry, dashboards, or live evaluation services +- Changing GitHub Actions unless the existing release docs cannot be expressed accurately without it + +### Task 1: Add Failing Protocol-Eval Contracts + +**Files:** +- Modify: `evals/test_run_evals.py` +- Modify: `evals/cases.csv` +- Test: `evals/test_run_evals.py` + +- [ ] **Step 1: Expand the eval tests to describe the protocol-era matrix** + +Update `evals/test_run_evals.py` so it fails against the current runner and seed data unless all of the following become true: +- the seed matrix now covers all six continuity packages +- the seed matrix grows beyond the old eight-row topology and includes protocol cases such as: + - `root_state_refresh` + - `root_state_compress` + - `subtask_split_from_root` + - `subtask_resume_from_packet` + - `packet_root_minimal_injection` + - `suite_bootstrap_protocol` +- normalized artifact tokens reference the new layout, for example: + - `suite/index` + - `root/task_state` + - `root/packet` + - `root/handoff` + - `subtask/task_state` + - `subtask/packet` + - `subtask/handoff` +- the runner result now contains cases for `skill-subtask-context` and `skill-context-packet` + +- [ ] **Step 2: Add a red seed matrix that reflects the intended protocol coverage** + +Replace the old rows in `evals/cases.csv` with the target protocol case IDs and tokens even though the current runner cannot score them yet. + +- [ ] **Step 3: Run the eval unit tests to verify the contract fails** + +Run: +```bash +cd /home/jn/projects/codex/codex-skill-library/.worktrees/continuity-maintenance +python3 -m unittest discover -s evals -p 'test_*.py' -v +``` +Expected: FAIL because the existing runner still hard-codes the old four-package matrix, flat artifact paths, and outdated event namespaces. + +- [ ] **Step 4: Commit the red-test checkpoint if you want the TDD breadcrumb** + +```bash +git add evals/test_run_evals.py evals/cases.csv +git commit -m "test: add protocol eval contracts" +``` + +### Task 2: Implement The Protocol-Aware Eval Harness + +**Files:** +- Modify: `evals/README.md` +- Modify: `evals/cases.csv` +- Modify: `evals/run_evals.py` +- Modify: `evals/test_run_evals.py` +- Test: `evals/test_run_evals.py` + +- [ ] **Step 1: Rewrite `PACKAGE_RULES` for the six-package continuity toolchain** + +Update `evals/run_evals.py` so the runner understands: +- `skill-context-keeper` as root-state refresh and compression +- `skill-subtask-context` as bounded child-task state ownership +- `skill-context-packet` as minimum next-turn context compression +- `skill-phase-gate` as optional checkpointing only +- `skill-handoff-summary` as root/subtask handoff generation +- `skill-task-continuity` as protocol bootstrap and composition + +Make the required file lists, trigger cues, suppress cues, artifact mappings, and event namespaces match the current package boundaries and asset layout. + +- [ ] **Step 2: Normalize the protocol matrix and workflow tokens** + +Refresh `evals/cases.csv` so the matrix covers: +- positive and negative routing for each package +- at least one protocol bootstrap case +- one root-state compression case +- one subtask-isolation case +- one packet-only continuation case + +Keep the matrix compact, but make it realistic enough to cover the five workflow-eval scenarios named in the spec. + +- [ ] **Step 3: Refresh the eval README around the new matrix** + +Update `evals/README.md` so maintainers can understand: +- why the matrix now uses root/subtask/packet tokens +- how the runner checks routing and boundary language for six packages +- how to extend the matrix without reintroducing flat-path assumptions + +- [ ] **Step 4: Re-run the eval unit tests and the static seed matrix** + +Run: +```bash +cd /home/jn/projects/codex/codex-skill-library/.worktrees/continuity-maintenance +python3 -m unittest discover -s evals -p 'test_*.py' -v +python3 evals/run_evals.py +``` +Expected: PASS, with the report scoring the protocol-era cases rather than the legacy flat-layout cases. + +- [ ] **Step 5: Commit the eval-harness slice** + +```bash +git add evals/README.md evals/cases.csv evals/run_evals.py evals/test_run_evals.py +git commit -m "feat: expand continuity evals for the context protocol" +``` + +### Task 3: Publish The Migration Guide And Refresh Public Suite Docs + +**Files:** +- Modify: `README.md` +- Modify: `README.zh-CN.md` +- Modify: `docs/long-task-suite.md` +- Modify: `docs/long-task-suite.zh-CN.md` +- Create: `docs/context-protocol-migration.md` +- Create: `docs/context-protocol-migration.zh-CN.md` + +- [ ] **Step 1: Write the migration guide in English** + +Create `docs/context-protocol-migration.md` with sections for: +- who needs to migrate and who can ignore the guide +- old four-package mental model vs new six-package protocol model +- how root state, subtask state, and packets map onto the older skills +- a recommended “start in beginner mode, expand later” adoption path +- common mistakes such as treating packets as full state or using phase-gate as the continuity center + +- [ ] **Step 2: Mirror the migration guide in Chinese** + +Create `docs/context-protocol-migration.zh-CN.md` with the same section order and examples adapted for Chinese readers. + +- [ ] **Step 3: Rewrite the suite overview docs around the current protocol** + +Update `docs/long-task-suite.md` and `docs/long-task-suite.zh-CN.md` so they: +- describe six packages instead of four +- explain the root/subtask/packet model as the continuity core +- replace the old flat-layout matrix table with the new protocol cases +- point readers to the migration guide for compatibility questions + +- [ ] **Step 4: Update the root README indexes** + +Refresh `README.md` and `README.zh-CN.md` so the repository root: +- lists `skill-subtask-context` and `skill-context-packet` +- links to `docs/context-protocol-migration.md` +- keeps the continuity suite discoverable from the repo landing page + +- [ ] **Step 5: Commit the migration-doc slice** + +```bash +git add README.md README.zh-CN.md docs/long-task-suite.md docs/long-task-suite.zh-CN.md docs/context-protocol-migration.md docs/context-protocol-migration.zh-CN.md +git commit -m "docs: publish context protocol migration guide" +``` + +### Task 4: Harden Publishing And Release Documentation + +**Files:** +- Modify: `CHANGELOG.md` +- Modify: `docs/publishing.md` +- Modify: `docs/publishing.zh-CN.md` +- Modify: `docs/release-checklist-long-task-suite.md` +- Modify: `docs/release-checklist-long-task-suite.zh-CN.md` +- Test: `evals/test_run_evals.py` + +- [ ] **Step 1: Remove stale fixed-target release wording** + +Update the publishing guide and release checklist so they no longer say the current continuity release target is `v0.6.1`. +Use release-scope-driven wording such as `` or explicit guidance to derive the next tag from `CHANGELOG.md` and the actual reader-visible scope. + +- [ ] **Step 2: Expand the continuity smoke-test loops to six packages** + +Rewrite the install-smoke examples in both publishing docs and both release-checklist docs so they include: +- `skills/skill-context-keeper` +- `skills/skill-subtask-context` +- `skills/skill-context-packet` +- `skills/skill-phase-gate` +- `skills/skill-handoff-summary` +- `skills/skill-task-continuity` + +- [ ] **Step 3: Update release guidance around protocol validation** + +Make the publishing docs explicitly require: +- package tests under `skills/*/tests` +- `skill-governance` validate-only packaging sanity +- the refreshed continuity eval unit tests +- the refreshed continuity seed matrix +- migration-doc and suite-overview spot checks before tagging + +- [ ] **Step 4: Refresh the changelog for the protocol rollout** + +Update `CHANGELOG.md` so the `Unreleased` section captures: +- the new protocol packages +- the layered bootstrap and refocused legacy boundaries +- the expanded eval harness +- the new migration and release docs + +- [ ] **Step 5: Commit the release-hardening slice** + +```bash +git add CHANGELOG.md docs/publishing.md docs/publishing.zh-CN.md docs/release-checklist-long-task-suite.md docs/release-checklist-long-task-suite.zh-CN.md +git commit -m "docs: harden context protocol release guidance" +``` + +### Task 5: Run Full Release-Facing Verification + +**Files:** +- Verify only + +- [ ] **Step 1: Run formatting and diff sanity** + +Run: +```bash +cd /home/jn/projects/codex/codex-skill-library/.worktrees/continuity-maintenance +git diff --check +``` +Expected: no whitespace or conflict-marker errors + +- [ ] **Step 2: Run all published package tests** + +Run: +```bash +cd /home/jn/projects/codex/codex-skill-library/.worktrees/continuity-maintenance +for test_dir in skills/*/tests; do + python3 -m unittest discover -s "$test_dir" -p 'test_*.py' -v +done +``` +Expected: PASS for every published package test directory + +- [ ] **Step 3: Run repository-level continuity validation** + +Run: +```bash +cd /home/jn/projects/codex/codex-skill-library/.worktrees/continuity-maintenance +python3 -m unittest discover -s evals -p 'test_*.py' -v +python3 evals/run_evals.py +(cd skills/skill-governance && python3 scripts/manage_skill.py --validate-only) +``` +Expected: PASS + +- [ ] **Step 4: Verify that stale release-target wording is gone from maintainer docs** + +Run: +```bash +cd /home/jn/projects/codex/codex-skill-library/.worktrees/continuity-maintenance +rg -n "current .*v0\\.6\\.1|target is `v0\\.6\\.1`|ref v0\\.6\\.1" docs README.md README.zh-CN.md evals +``` +Expected: either no matches in maintainer docs, or only intentional historical references outside the release-facing continuity guidance + +- [ ] **Step 5: Commit the verification checkpoint or final batch** + +```bash +git status --short +``` +Expected: clean worktree if all slice-3 commits were created along the way + +## Final Review Checklist + +- The eval harness understands six continuity packages and root/subtask/packet artifact tokens. +- The seed matrix covers the spec’s workflow-eval scenarios without exploding into noisy duplicates. +- The migration guide gives existing users a concrete adoption path instead of just re-explaining the spec. +- The suite overview and repo root no longer describe a four-package continuity system. +- Publishing and release docs no longer hard-code a stale release target. diff --git a/docs/superpowers/specs/2026-03-26-context-protocol-repo-workflow-design.md b/docs/superpowers/specs/2026-03-26-context-protocol-repo-workflow-design.md new file mode 100644 index 0000000..a7fd76b --- /dev/null +++ b/docs/superpowers/specs/2026-03-26-context-protocol-repo-workflow-design.md @@ -0,0 +1,440 @@ +# Context Protocol + Repo Workflow Design + +**Date:** 2026-03-26 +**Status:** Draft +**Scope:** Product model and implementation direction for the next generation of the long-task continuity suite +**Audience:** Maintainers of `codex-skill-library` and downstream users adopting the suite for long-running coding tasks + +## Summary + +The current long-task continuity suite already provides useful continuity primitives: +state refresh, checkpoints, handoff writing, and bootstrap guidance. +It does not yet behave like a full context-management system for small-team or multi-agent work. + +This design proposes a layered hybrid model: + +- a **Context Protocol** that defines how task state, subtask state, context packets, compression, and handoff should work +- a **Repo Workflow** that makes the protocol usable through repository files, default wrappers, and lightweight operational flows + +The goal is to let agents resume, split, hand off, and compress work without rereading entire thread histories or flooding the active context window with stale information. + +## Problem Statement + +The current suite is strong on package boundaries and durable artifacts, but it still has four major product gaps: + +1. **Subtask isolation is weak** + The suite does not yet model subtasks as first-class context owners with independent state and handoff surfaces. +2. **Just-in-time context injection is implicit** + Current guidance helps users choose the next skill, but does not define a minimal context packet for the next action. +3. **Compression is template-level, not system-level** + Current artifacts are compact, but there is no explicit lifecycle for pruning, rolling up, and archiving stale state. +4. **Day-2 operation still expects informed users** + Installation is friendly, but sustained use still depends on manual judgment about which artifact to update and which context to carry forward. + +## Target Users + +### Primary User + +Small teams or multi-agent workflows that need: + +- durable task continuity across sessions +- safe subtask splitting +- low-noise handoffs +- predictable repo-local artifacts that can be shared by humans and agents + +### Secondary User + +Individual developers running long tasks in a single repository who still benefit from the same repo-first workflow, even if they never use multiple concurrent agents. + +## Product Goals + +### 1. Context Isolation + +Subtasks must have independent local context so execution noise from one unit of work does not contaminate another. + +### 2. Just-In-Time Injection + +Agents should receive the minimum sufficient context for the next action instead of broad, eager context loading. + +### 3. Context Compression + +The active context window should stay lean while useful history remains available through layered summaries and archive paths. + +### 4. Beginner-Friendly Adoption + +The default repository workflow must be simple enough that a new user can succeed without first understanding the full protocol model. + +## Non-Goals + +- This project is not trying to become a general project-management system. +- This project is not trying to replace issue trackers, kanban tools, or long-form project docs. +- This project is not trying to create hidden automatic orchestration that users cannot inspect. +- This project is not required to preserve the exact current four-skill topology. +- V1 does not need native integrations for every agent platform if the repo-first workflow is coherent and portable. + +## Design Principles + +### Protocol First, Repo First In Practice + +The protocol must be defined clearly before the workflow is implemented, but the first user experience should still be repository files and natural-language invocation. + +### State Is Layered + +Current state, subtask state, handoff state, and execution logs must not collapse into one undifferentiated summary. + +### Minimal Sufficient Context + +Default injection should be constrained to the smallest useful packet for the current action. + +### Compression Is Active Work + +Compression is not "write a shorter paragraph." It is the deliberate movement of information between active, working, and archive layers. + +### Subtasks Are First-Class Objects + +A subtask is not a note under the root task. It is an independent context unit with its own state, packet, log, and handoff surface. + +### Beginner Path Must Be Obvious + +The suite should scale up to multi-agent workflows without forcing single-repo users to adopt the full model on day one. + +## Chosen Direction + +This design uses a **Layered Hybrid Model**: + +- **Layer 1: Context Protocol** + Defines the object model, state lifecycle, packet rules, injection rules, and handoff contract. +- **Layer 2: Repo Workflow** + Applies the protocol to repository files, bootstrap helpers, wrappers, and day-to-day usage flows. + +This model is preferred over a small evolution of the current four-skill suite because the missing capabilities are structural, not cosmetic. +It is preferred over a protocol-only redesign because the default user experience still needs to be approachable in ordinary repositories. + +## Core Object Model + +### Root Task + +The top-level context owner for a long-running effort. + +It holds: + +- global objective +- global constraints +- shared verified facts +- cross-cutting risks +- current top-level status +- open subtasks + +The root task should remain trustworthy and durable, but not overloaded with every local detail. + +### Subtask + +A child execution unit derived from the root task. + +It holds: + +- local objective +- local scope and non-goals +- inherited constraints that still apply +- local verified facts +- local decisions +- local risks +- local next action + +Subtasks must be resumable and handoff-ready on their own. + +### Context Layers + +Every task object is organized into three layers: + +- **Active Layer** + What the next action must know now. +- **Working Layer** + Useful near-term state that does not belong in the default injected packet. +- **Archive Layer** + Retained history that should not occupy active context unless explicitly requested. + +### Context Packet + +The minimum injection unit used to start or continue an action. + +A packet should include only: + +- current objective +- directly relevant constraints +- verified facts required for the action +- active risks or blockers +- exact next action +- minimal file or module references when needed + +Packets are narrower than full task state and are the default artifact for agent injection. + +### Handoff Contract + +The standard continuation object for pauses or transfers. + +A handoff must capture: + +- current status +- preserved constraints +- open problems +- exact next action +- files or artifacts to inspect first +- resume wording for the next session + +## Context Lifecycle + +### Creation + +- A root task is initialized when continuity starts for a repo or meaningful workstream. +- A subtask is created when a branch of work can proceed with partially independent local state. + +### Refresh + +- Root and subtask state are refreshed when the trusted picture changes materially. +- Refresh must preserve facts, separate assumptions, and record decisions already made. + +### Injection + +- Default injection should use the target object's packet first. +- Broader task state is loaded only if the packet is insufficient. + +### Compression + +- Fresh findings begin in the working layer. +- Active, currently necessary items are promoted into the packet or active task summary. +- Stale but still relevant details are archived. +- Repeated or superseded items should be folded or deleted rather than endlessly appended. + +### Closure + +- A closed subtask should be marked resolved, merged back into root state where needed, and archived. +- A root task can produce a final handoff or closure summary, but only after its active subtasks are resolved or explicitly deferred. + +## Injection Rules + +### Default Rule + +Inject only the current subtask's active packet. + +### Escalation Rule + +If the action depends on global constraints or shared decisions, inject the minimal root-task packet supplement. + +### Recovery Rule + +If the packet cannot support progress, read the corresponding task state file before scanning logs or archives. + +### Anti-Rule + +Do not inject: + +- the whole thread +- every task artifact +- every open subtask +- the full run log + +unless the current action explicitly requires reconstruction at that scope. + +## Recommended Repo Workflow + +### Default Layout + +```text +AGENTS.md +.agent-state/ + INDEX.md + root/ + TASK_STATE.md + PACKET.md + DECISIONS.md + RUN_LOG.md + HANDOFF.md + subtasks/ + / + TASK_STATE.md + PACKET.md + HANDOFF.md + RUN_LOG.md + archive/ + root/ + subtasks/ + packets/ +``` + +### Layout Semantics + +- `INDEX.md` is the operator entry point. + It answers which root task is active, which subtasks are open, and which packets are current. +- `root/TASK_STATE.md` holds durable top-level state. +- `root/PACKET.md` is the default injected summary for root-level work. +- `subtasks//TASK_STATE.md` is the durable local state for a subtask. +- `subtasks//PACKET.md` is the default injected context for that subtask. +- `archive/` stores retired or compressed artifacts that should stay discoverable without polluting active state. + +### Beginner Mode + +V1 should allow a lightweight mode: + +```text +AGENTS.md +.agent-state/ + INDEX.md + root/ + TASK_STATE.md + PACKET.md + HANDOFF.md +``` + +Users only expand into `subtasks/` and `archive/` when the task complexity justifies it. + +## Recommended Workflow Loop + +1. Read `INDEX.md`. +2. Open the current target packet. +3. If the work is large enough to split, create a subtask. +4. Execute using the subtask packet, not the full root state. +5. Refresh subtask state after meaningful changes. +6. Merge durable outcomes back into root state where necessary. +7. Compress stale detail into archive rather than growing active state indefinitely. +8. Write a handoff before a meaningful pause or transfer. + +## Recommended Skill Topology + +This design does **not** require preserving the current four-skill topology unchanged. + +### Keep And Refocus + +- **`skill-task-continuity`** + Suite entry point, bootstrap helper, router, and mode selector. +- **`skill-context-keeper`** + Root-task refresh and compression-focused state maintenance. +- **`skill-handoff-summary`** + Standard handoff contract for root tasks and subtasks. +- **`skill-phase-gate`** + Optional operational checkpoint for risky edits, no longer the center of the system. + +### Add + +- **`skill-subtask-context`** + Create, refresh, hand off, and close subtask context units. +- **`skill-context-packet`** + Build or refresh minimal context packets for the next action. + +### Why This Split + +- `skill-context-keeper` maps to trusted durable state. +- `skill-subtask-context` maps to isolation. +- `skill-context-packet` maps to just-in-time injection. +- `skill-handoff-summary` maps to continuation transfers. +- `skill-task-continuity` maps to adoption and orchestration. +- `skill-phase-gate` remains valuable for risk management, but should not be overloaded as a context-management primitive. + +## Bootstrap And Wrapper Strategy + +Bootstrap should create: + +- `AGENTS.md` +- `.agent-state/INDEX.md` +- root-state starter files +- optional beginner wrappers under `.agents/skills/` + +Suggested default wrappers: + +- `refresh-root-state` +- `create-subtask` +- `refresh-subtask-packet` +- `write-handoff` +- `compress-context` + +These wrappers should remain thin and point back to the canonical public skills instead of copying their behavior. + +## Migration Strategy + +### Near-Term + +- Preserve the current four packages so downstream users do not break immediately. +- Add compatibility documentation that explains the emerging protocol model. + +### Mid-Term + +- Introduce `skill-subtask-context` and `skill-context-packet`. +- Update `skill-task-continuity` to bootstrap the new repo layout. +- Refocus `skill-context-keeper` on root-state refresh and compression. + +### Long-Term + +- Re-evaluate whether the older package names still reflect the product model. +- Retire or merge packages only after wrappers, docs, and tests cover the new workflow clearly. + +## V1 Scope + +V1 should ship: + +- a written context protocol +- beginner and expanded repo layouts +- root task state and packet artifacts +- subtask state and packet artifacts +- standardized handoff contract +- compression guidance with archive movement +- suite entry guidance that helps users choose the next action + +V1 does **not** need: + +- automatic graph scheduling of all subtasks +- deep platform-specific integrations +- fully automatic compression without user-visible rules + +## Validation Strategy + +### Contract Tests + +Add tests that verify: + +- subtask artifacts exist and are structurally distinct from root artifacts +- packets are narrower than task state and preserve required sections +- handoff artifacts work for both root and subtask scopes +- beginner bootstrap and expanded bootstrap both produce expected files +- archive and compression flows preserve active-state clarity + +### Workflow Evals + +Add task-based evals for: + +- split one root task into two subtasks without context bleed +- resume a subtask from packet plus handoff only +- recover after multiple sessions without rereading the whole thread +- compress bloated state back into a lean active packet +- onboard a new downstream repo from bootstrap to first successful handoff + +## Success Criteria + +The design is successful when a new repo can support this path: + +1. bootstrap continuity files +2. create a root task +3. split a subtask +4. inject only the subtask packet into execution +5. pause with a valid handoff +6. resume without rereading the full history +7. keep active state lean across multiple cycles + +## Risks + +### Over-Modeling + +If the protocol is too abstract, normal users will not adopt it. + +### Under-Modeling + +If subtask state and packets remain vague, the suite will keep behaving like a set of generic summaries instead of a context system. + +### Wrapper Drift + +If repo-local wrappers become thick forks, the public package model will fragment. + +## Recommendation + +Proceed with the layered hybrid redesign. +Keep the repo-first experience simple, but do not hide the underlying protocol. +The future suite should be judged less by how many markdown templates it ships and more by whether it can reliably isolate, inject, compress, and transfer context in real multi-agent work. diff --git a/evals/README.md b/evals/README.md index 62df1a8..83840f6 100644 --- a/evals/README.md +++ b/evals/README.md @@ -1,19 +1,43 @@ -# Long-Task Continuity Evals +# Context Protocol Evals -This directory contains the static, repo-driven evaluation harness for the long-task continuity suite. -It uses `evals/cases.csv` as the seed matrix and checks the published repository shape rather than executing a model. +This directory contains the static, repo-driven evaluation harness for the context-protocol continuity suite. +It uses `evals/cases.csv` as the seed matrix and validates the published repository shape rather than executing a model. ## What It Checks -- CSV parsing and normalization -- should-trigger vs should-not-trigger coverage from prompt polarity -- expected artifact templates for each package, with strict token-to-template mapping -- routing hints in `SKILL.md` and package READMEs, plus prompt polarity evidence -- boundary language and non-overlap guidance in package READMEs -- expected event tokens by exact package and polarity contract -- suite-level downstream templates and assets for `skill-task-continuity` +- CSV parsing and normalization for the protocol-era seed matrix +- six-package routing coverage across: + - `skill-context-keeper` + - `skill-subtask-context` + - `skill-context-packet` + - `skill-phase-gate` + - `skill-handoff-summary` + - `skill-task-continuity` +- root / subtask / packet artifact mapping with strict token-to-template validation +- routing hints in `SKILL.md`, package READMEs, and prompt polarity +- boundary language and non-overlap guidance in package docs +- exact workflow-event namespaces by package and polarity contract +- suite-level bootstrap assets for `AGENTS.md`, `.agent-state/INDEX.md`, root artifacts, and subtask artifacts - static guardrail metadata validation when optional columns are present +## Matrix Conventions + +The seed matrix uses normalized artifact tokens instead of raw downstream paths. +Current token families include: + +- `root/task_state` +- `root/packet` +- `root/handoff` +- `subtask/task_state` +- `subtask/packet` +- `subtask/handoff` +- `phase/preflight` +- `phase/postflight` +- `suite/agents` +- `suite/index` + +This keeps the eval surface stable even when multiple packages point to the same downstream file shape. + ## Run It ```bash @@ -35,5 +59,14 @@ python3 -m unittest discover -s evals -p 'test_*.py' -v ## Adding Cases Add a new row to `evals/cases.csv`, then rerun the harness. -If the case needs optional guardrails later, add the relevant CSV columns and the runner will validate `max_commands > 0` and `max_verbosity` in `low|medium|high`. -For polarity-sensitive cases, make sure the prompt cues, routing docs, expected events, and artifact tokens all match the package’s routing boundary. + +Prefer cases that add real routing pressure instead of paraphrasing an existing row: + +- root-state refresh vs packet compression +- root vs subtask ownership +- packet-only continuation vs full-state refresh +- risky checkpoint vs trivial edit +- handoff vs in-thread status chatter +- suite bootstrap vs a single atomic action + +If a case needs optional guardrails later, add the relevant CSV columns and the runner will validate `max_commands > 0` and `max_verbosity` in `low|medium|high`. diff --git a/evals/cases.csv b/evals/cases.csv index 20fb9dc..1940f04 100644 --- a/evals/cases.csv +++ b/evals/cases.csv @@ -1,9 +1,15 @@ case_id,package,scenario_type,should_trigger,user_prompt,expected_artifacts,expected_events,notes -context_resume,skill-context-keeper,positive,yes,"We’ve been iterating for a while; please resume from the last known state, summarize what changed, and carry forward unresolved TODOs.","state/context.snapshot|state/continuity.note","context:reload|context:reconstruct|context:summary","atomic positive trigger for state reconstruction" -context_resume_not_needed,skill-context-keeper,negative,no,"Please answer this one-off punctuation question in the README and do nothing else.","none","context:skip|direct:answer","atomic negative trigger; no long-thread drift" -phase_gate_before_multi_step,skill-phase-gate,positive,yes,"We need to refactor the installer and update docs; help me split the work into phases before coding.","plan/phase.plan|plan/checkpoints.md|plan/exit-criteria.md","phase:split|phase:checkpoint|phase:gate","atomic positive trigger for workflow gating" -tiny_edit_not_gate,skill-phase-gate,negative,no,"Please rename this heading and nothing else.","none","phase:skip|direct:edit","required example" -handoff_before_pause,skill-handoff-summary,positive,yes,"I need to stop for today; please write a handoff with open questions, blockers, and next steps.","handoff/HANDOFF.md|handoff/blockers.md|handoff/next-steps.md","handoff:capture|handoff:pause|handoff:transfer","required example" -handoff_not_needed,skill-handoff-summary,negative,no,"Just give me the final answer; no status note or handoff is needed.","none","handoff:skip|direct:answer","atomic negative trigger" -suite_bootstrap,skill-task-continuity,positive,yes,"Set up the long-task continuity suite and coordinate the context keeper, phase gate, and handoff packages.","AGENTS.md|.agent-state/TASK_STATE.md|.agent-state/HANDOFF.md","bootstrap:agents_md|bootstrap:task_state|bootstrap:handoff","composition-package positive trigger" -suite_boundary_clean,skill-task-continuity,negative,no,"This is just a one-line README fix, but please also resume context, gate the phases, and write a handoff.","none","bootstrap:skip|direct:edit","cross-package ambiguity case; boundaries should stay clean" +root_state_refresh,skill-context-keeper,positive,yes,"Rebuild the current root task picture from the repo and update .agent-state/root/TASK_STATE.md before we continue.","root/task_state","root:refresh|root:reconcile|root:compress","root-task refresh trigger for verified state reconciliation" +root_state_compress,skill-context-keeper,positive,yes,"The root task state is bloated; compress it and move stale detail out of active state without creating a packet-only handoff.","root/task_state","root:refresh|root:reconcile|root:compress","root-state compression trigger" +root_state_refresh_not_needed,skill-context-keeper,negative,no,"Please answer this one-off punctuation question in the README and do nothing else.","none","root:skip|route:other","root-state refresh should not trigger for trivial one-off asks" +subtask_split_from_root,skill-subtask-context,positive,yes,"Split this bounded child task out of the root thread and create local state under .agent-state/subtasks//TASK_STATE.md.","subtask/task_state","subtask:split|subtask:refresh|subtask:isolate","subtask isolation trigger from root work" +subtask_resume_from_packet,skill-subtask-context,positive,yes,"Resume the child task from its packet and refresh the subtask-local state without bloating root context.","subtask/task_state","subtask:split|subtask:refresh|subtask:isolate","subtask-local resume trigger" +subtask_state_not_needed,skill-subtask-context,negative,no,"Just refresh the root task state; do not open a separate child task.","none","subtask:skip|route:root_or_packet","subtask package should stay out when no child-task boundary is needed" +packet_root_minimal_injection,skill-context-packet,positive,yes,"Compress the next root turn into a minimal packet at .agent-state/root/PACKET.md instead of loading the full state file.","root/packet","packet:compose|packet:trim|packet:inject","packet-sized root continuation trigger" +packet_not_needed_for_full_refresh,skill-context-packet,negative,no,"Refresh the full root task state from the codebase; do not compress it into a packet.","none","packet:skip|route:state_or_handoff","packet package should stay out when the user wants full-state refresh" +phase_gate_risky_checkpoint,skill-phase-gate,positive,yes,"Run a checkpoint before and after this risky multi-file refactor so the exit criteria stay explicit.","phase/preflight|phase/postflight","phase:preflight|phase:checkpoint|phase:postflight","optional checkpoint trigger for risky execution" +tiny_edit_not_gate,skill-phase-gate,negative,no,"Please rename this heading and nothing else.","none","phase:skip|direct:edit","tiny edits should not route to phase-gate" +handoff_subtask_pause,skill-handoff-summary,positive,yes,"I need to pause this child task; write a compact handoff for .agent-state/subtasks//HANDOFF.md with blockers and next steps.","subtask/handoff","handoff:capture|handoff:pause|handoff:resume","subtask pause handoff trigger" +handoff_not_needed,skill-handoff-summary,negative,no,"Just give me the final answer; no handoff or status artifact is needed.","none","handoff:skip|direct:answer","handoff package should stay out when no continuation artifact is requested" +suite_bootstrap_protocol,skill-task-continuity,positive,yes,"Bootstrap the context protocol in this repo and route me between root state, subtasks, packets, checkpoints, and handoffs.","suite/agents|suite/index|root/task_state|root/packet|root/handoff|subtask/task_state|subtask/packet|subtask/handoff","suite:bootstrap|suite:route|suite:explain","protocol bootstrap and composition trigger" +suite_boundary_clean,skill-task-continuity,negative,no,"This is just a one-line README fix, even if I mentioned root state, subtasks, packets, and handoffs in passing.","none","suite:skip|direct:edit","composition package should stay out of trivial edits even when keywords appear" diff --git a/evals/run_evals.py b/evals/run_evals.py index 89893bd..16817dd 100644 --- a/evals/run_evals.py +++ b/evals/run_evals.py @@ -47,29 +47,24 @@ class EvalCase: "assets/TASK_STATE.template.md", ], "trigger_cues": [ - "use this skill when", - "resuming a task", - "resume from the last known state", - "refresh state", - "rebuilding the last known task state", - "carry forward unresolved todo", - "carry forward unresolved todos", - "update .agent-state/task_state.md", + "root-state refresh", + ".agent-state/root/task_state.md", + "root task state", + "compression", + "reconciling root-state changes", ], "suppress_cues": [ "one-off", "do nothing else", - "just answer", - "punctuation question", + "does not own subtask state", "does not own workflow gating", "does not own final handoffs", ], "artifact_map": { - "state/context.snapshot": "assets/TASK_STATE.template.md", - "state/continuity.note": "assets/TASK_STATE.template.md", + "root/task_state": "assets/TASK_STATE.template.md", }, - "positive_events": ["context:reload", "context:reconstruct", "context:summary"], - "negative_events": ["context:skip", "direct:answer"], + "positive_events": ["root:refresh", "root:reconcile", "root:compress"], + "negative_events": ["root:skip", "route:other"], "workflow_files": [ "references/use-cases.md", "references/use-cases.zh-CN.md", @@ -77,6 +72,86 @@ class EvalCase: "references/prompt-templates.zh-CN.md", ], }, + "skill-subtask-context": { + "required_files": [ + "README.md", + "README.zh-CN.md", + "SKILL.md", + "references/README.md", + "references/README.zh-CN.md", + "references/use-cases.md", + "references/use-cases.zh-CN.md", + "references/prompt-templates.en.md", + "references/prompt-templates.zh-CN.md", + "assets/TASK_STATE.template.md", + ], + "trigger_cues": [ + "child task", + ".agent-state/subtasks//task_state.md", + "local child-task state", + "parent context minimal", + ], + "suppress_cues": [ + "root task state", + "packet compression", + "workflow gates", + "final handoffs", + ], + "artifact_map": { + "subtask/task_state": "assets/TASK_STATE.template.md", + }, + "positive_events": ["subtask:split", "subtask:refresh", "subtask:isolate"], + "negative_events": ["subtask:skip", "route:root_or_packet"], + "workflow_files": [ + "references/README.md", + "references/README.zh-CN.md", + "references/use-cases.md", + "references/use-cases.zh-CN.md", + "references/prompt-templates.en.md", + "references/prompt-templates.zh-CN.md", + ], + }, + "skill-context-packet": { + "required_files": [ + "README.md", + "README.zh-CN.md", + "SKILL.md", + "references/README.md", + "references/README.zh-CN.md", + "references/use-cases.md", + "references/use-cases.zh-CN.md", + "references/prompt-templates.en.md", + "references/prompt-templates.zh-CN.md", + "assets/PACKET.template.md", + ], + "trigger_cues": [ + "minimum context packet", + ".agent-state/root/packet.md", + ".agent-state/subtasks//packet.md", + "packet-first workflow", + "small packet of facts", + ], + "suppress_cues": [ + "full root task state", + "workflow gates", + "handoff summary", + "suite bootstrap", + ], + "artifact_map": { + "root/packet": "assets/PACKET.template.md", + "subtask/packet": "assets/PACKET.template.md", + }, + "positive_events": ["packet:compose", "packet:trim", "packet:inject"], + "negative_events": ["packet:skip", "route:state_or_handoff"], + "workflow_files": [ + "references/README.md", + "references/README.zh-CN.md", + "references/use-cases.md", + "references/use-cases.zh-CN.md", + "references/prompt-templates.en.md", + "references/prompt-templates.zh-CN.md", + ], + }, "skill-phase-gate": { "required_files": [ "README.md", @@ -92,37 +167,34 @@ class EvalCase: "assets/POSTFLIGHT.template.md", ], "trigger_cues": [ - "meaningful coding checkpoint", + "optional operational checkpoint", "preflight", "postflight", - "split", - "phases", - "multi-step", - "refactor", - "before coding", - "use this skill when", + "risky", + "multi-file", + "checkpoint", ], "suppress_cues": [ - "not for trivial one-line edits", - "tiny edit", + "trivial one-line edit", "rename this heading", - "one-line change", - "not for pure explanation tasks", - "does not replace planning packages", - "does not become a handoff generator", + "pure explanation task", + "root-state refresh", + "packet compression", + "suite bootstrap", ], "artifact_map": { - "plan/phase.plan": "assets/PREFLIGHT.template.md", - "plan/checkpoints.md": "assets/PREFLIGHT.template.md", - "plan/exit-criteria.md": "assets/POSTFLIGHT.template.md", + "phase/preflight": "assets/PREFLIGHT.template.md", + "phase/postflight": "assets/POSTFLIGHT.template.md", }, - "positive_events": ["phase:split", "phase:checkpoint", "phase:gate"], + "positive_events": ["phase:preflight", "phase:checkpoint", "phase:postflight"], "negative_events": ["phase:skip", "direct:edit"], "workflow_files": [ "references/README.md", "references/README.zh-CN.md", "references/use-cases.md", "references/use-cases.zh-CN.md", + "references/prompt-templates.en.md", + "references/prompt-templates.zh-CN.md", "assets/PREFLIGHT.template.md", "assets/POSTFLIGHT.template.md", ], @@ -142,35 +214,31 @@ class EvalCase: ], "trigger_cues": [ "continuation-oriented", - "handoff", - "write a handoff", "pause", "transfer", - "use this skill when", - "writing or refreshing a compact artifact such as `.agent-state/handoff.md`", + ".agent-state/root/handoff.md", + ".agent-state/subtasks//handoff.md", ], "suppress_cues": [ "final answer", "no handoff", - "just give me", - "do nothing else", - "does not own long-term state", - "does not own workflow gating", - "not a full-project documentation", - "replacing the final user-facing answer when no handoff is needed", + "quick status note", + "whole-project documentation", + "does not own workflow gates", ], "artifact_map": { - "handoff/HANDOFF.md": "assets/HANDOFF.template.md", - "handoff/blockers.md": "assets/HANDOFF.template.md", - "handoff/next-steps.md": "assets/HANDOFF.template.md", + "root/handoff": "assets/HANDOFF.template.md", + "subtask/handoff": "assets/HANDOFF.template.md", }, - "positive_events": ["handoff:capture", "handoff:pause", "handoff:transfer"], + "positive_events": ["handoff:capture", "handoff:pause", "handoff:resume"], "negative_events": ["handoff:skip", "direct:answer"], "workflow_files": [ "references/README.md", "references/README.zh-CN.md", "references/use-cases.md", "references/use-cases.zh-CN.md", + "references/prompt-templates.en.md", + "references/prompt-templates.zh-CN.md", "assets/HANDOFF.template.md", ], }, @@ -179,43 +247,62 @@ class EvalCase: "README.md", "README.zh-CN.md", "SKILL.md", + "references/README.md", + "references/README.zh-CN.md", "references/composition-guide.md", + "references/composition-guide.zh-CN.md", "references/install-playbook.md", + "references/install-playbook.zh-CN.md", "assets/AGENTS.repo-template.md", - "assets/agent-state/TASK_STATE.template.md", - "assets/agent-state/HANDOFF.template.md", - "assets/agent-state/DECISIONS.template.md", - "assets/agent-state/RUN_LOG.template.md", + "assets/agent-state/INDEX.template.md", + "assets/agent-state/root/TASK_STATE.template.md", + "assets/agent-state/root/PACKET.template.md", + "assets/agent-state/root/HANDOFF.template.md", + "assets/agent-state/subtasks/TASK_STATE.template.md", + "assets/agent-state/subtasks/PACKET.template.md", + "assets/agent-state/subtasks/HANDOFF.template.md", ], "trigger_cues": [ - "bootstrapping the long-task continuity suite", - "continuity suite", - "set up the long-task continuity suite", - "coordinate", - "deciding which atomic package should trigger first", - "composition boundary", - "use this skill when", + "continuity workflow", + "bootstrap", + ".agent-state/index.md", + "packet-first", + "route to the atomic skills", ], "suppress_cues": [ "one-line readme fix", - "trivial edit", - "do not use this package to mutate the public library root into a consumer repo", - "does not replace the three atomic skills", - "route suite-shaped requests to the atomic package", + "one atomic package", + "only need to refresh task state", + "does not replace the atomic skills", + "public library checkout into a consumer repo", ], "artifact_map": { - "AGENTS.md": "assets/AGENTS.repo-template.md", - ".agent-state/TASK_STATE.md": "assets/agent-state/TASK_STATE.template.md", - ".agent-state/HANDOFF.md": "assets/agent-state/HANDOFF.template.md", + "suite/agents": "assets/AGENTS.repo-template.md", + "suite/index": "assets/agent-state/INDEX.template.md", + "root/task_state": "assets/agent-state/root/TASK_STATE.template.md", + "root/packet": "assets/agent-state/root/PACKET.template.md", + "root/handoff": "assets/agent-state/root/HANDOFF.template.md", + "subtask/task_state": "assets/agent-state/subtasks/TASK_STATE.template.md", + "subtask/packet": "assets/agent-state/subtasks/PACKET.template.md", + "subtask/handoff": "assets/agent-state/subtasks/HANDOFF.template.md", }, - "positive_events": ["bootstrap:agents_md", "bootstrap:task_state", "bootstrap:handoff"], - "negative_events": ["bootstrap:skip", "direct:edit"], + "positive_events": ["suite:bootstrap", "suite:route", "suite:explain"], + "negative_events": ["suite:skip", "direct:edit"], "workflow_files": [ + "references/README.md", + "references/README.zh-CN.md", "references/composition-guide.md", + "references/composition-guide.zh-CN.md", "references/install-playbook.md", + "references/install-playbook.zh-CN.md", "assets/AGENTS.repo-template.md", - "assets/agent-state/TASK_STATE.template.md", - "assets/agent-state/HANDOFF.template.md", + "assets/agent-state/INDEX.template.md", + "assets/agent-state/root/TASK_STATE.template.md", + "assets/agent-state/root/PACKET.template.md", + "assets/agent-state/root/HANDOFF.template.md", + "assets/agent-state/subtasks/TASK_STATE.template.md", + "assets/agent-state/subtasks/PACKET.template.md", + "assets/agent-state/subtasks/HANDOFF.template.md", ], }, } diff --git a/evals/test_release_docs.py b/evals/test_release_docs.py new file mode 100644 index 0000000..c676d6d --- /dev/null +++ b/evals/test_release_docs.py @@ -0,0 +1,36 @@ +import unittest +from pathlib import Path + + +ROOT = Path(__file__).resolve().parents[1] + +RELEASE_FACING_DOCS = [ + "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-task-continuity/README.md", + "skills/skill-task-continuity/README.zh-CN.md", + "skills/skill-governance/README.md", + "skills/skill-governance/README.zh-CN.md", + "skills/skill-governance/docs/publishing-with-skill-installer.md", + "skills/skill-governance/docs/publishing-with-skill-installer.zh-CN.md", + "skills/skill-governance/references/use-cases.md", + "skills/skill-governance/references/use-cases.zh-CN.md", +] + + +class ReleaseDocsTests(unittest.TestCase): + def test_release_facing_docs_do_not_pin_a_stale_fixed_tag(self): + for relative in RELEASE_FACING_DOCS: + path = ROOT / relative + self.assertTrue(path.exists(), f"missing release-facing doc: {relative}") + text = path.read_text(encoding="utf-8") + with self.subTest(path=relative): + self.assertNotIn("v0.6.1", text) + + +if __name__ == "__main__": + unittest.main() diff --git a/evals/test_run_evals.py b/evals/test_run_evals.py index a356195..b757f51 100644 --- a/evals/test_run_evals.py +++ b/evals/test_run_evals.py @@ -1,10 +1,10 @@ import csv import importlib.util import re -import tempfile +import shutil import sys +import tempfile import unittest -import shutil from pathlib import Path @@ -54,7 +54,7 @@ def test_seed_cases_csv_has_expected_columns(self): with CASES_CSV.open(encoding="utf-8", newline="") as handle: rows = list(csv.DictReader(handle)) - self.assertEqual(len(rows), 8) + self.assertEqual(len(rows), 14) self.assertEqual( list(rows[0].keys()), [ @@ -69,48 +69,69 @@ def test_seed_cases_csv_has_expected_columns(self): ], ) + def test_package_rules_cover_protocol_packages(self): + self.assertTrue(RUNNER.exists(), "evaluation runner should exist") + module = load_runner_module() + + self.assertEqual( + set(module.PACKAGE_RULES), + { + "skill-context-keeper", + "skill-subtask-context", + "skill-context-packet", + "skill-phase-gate", + "skill-handoff-summary", + "skill-task-continuity", + }, + ) + def test_load_cases_normalizes_seed_matrix(self): self.assertTrue(RUNNER.exists(), "evaluation runner should exist") module = load_runner_module() cases = module.load_cases(CASES_CSV) - self.assertEqual(len(cases), 8) - context_resume = next(case for case in cases if case.case_id == "context_resume") - self.assertTrue(context_resume.should_trigger) + self.assertEqual(len(cases), 14) + root_refresh = next(case for case in cases if case.case_id == "root_state_refresh") + self.assertTrue(root_refresh.should_trigger) + self.assertEqual(root_refresh.expected_artifacts, ["root/task_state"]) self.assertEqual( - context_resume.expected_artifacts, - ["state/context.snapshot", "state/continuity.note"], + root_refresh.expected_events, + ["root:refresh", "root:reconcile", "root:compress"], ) - self.assertEqual( - context_resume.expected_events, - ["context:reload", "context:reconstruct", "context:summary"], + + subtask_resume = next( + case for case in cases if case.case_id == "subtask_resume_from_packet" ) + self.assertEqual(subtask_resume.package, "skill-subtask-context") + self.assertEqual(subtask_resume.expected_artifacts, ["subtask/task_state"]) suite_boundary_clean = next( case for case in cases if case.case_id == "suite_boundary_clean" ) self.assertFalse(suite_boundary_clean.should_trigger) - def test_run_evaluations_produces_case_and_dimension_results(self): + def test_run_evaluations_produces_passing_protocol_results(self): self.assertTrue(RUNNER.exists(), "evaluation runner should exist") module = load_runner_module() result = module.run_evaluations(ROOT, CASES_CSV) - self.assertEqual(result["summary"]["cases"], 8) - self.assertIn("passed", result["summary"]) - self.assertIn("failed", result["summary"]) + self.assertEqual(result["summary"]["cases"], 14) + self.assertEqual(result["summary"]["failed"], 0) + self.assertEqual(result["summary"]["passed"], 14) self.assertIn("routing_quality", result["dimensions"]) self.assertIn("artifact_presence", result["dimensions"]) self.assertIn("workflow_completeness", result["dimensions"]) self.assertIn("docs_clarity", result["dimensions"]) - case = next(item for item in result["cases"] if item["case_id"] == "suite_bootstrap") - self.assertIn("routing_quality", case["dimensions"]) - self.assertIn("artifact_presence", case["dimensions"]) - self.assertIn("workflow_completeness", case["dimensions"]) - self.assertIn("docs_clarity", case["dimensions"]) + case = next( + item for item in result["cases"] if item["case_id"] == "suite_bootstrap_protocol" + ) + self.assertEqual(case["dimensions"]["routing_quality"]["status"], "pass") + self.assertEqual(case["dimensions"]["artifact_presence"]["status"], "pass") + self.assertEqual(case["dimensions"]["workflow_completeness"]["status"], "pass") + self.assertEqual(case["dimensions"]["docs_clarity"]["status"], "pass") def test_optional_guardrail_columns_are_supported(self): self.assertTrue(RUNNER.exists(), "evaluation runner should exist") @@ -123,12 +144,12 @@ def test_optional_guardrail_columns_are_supported(self): [ { "case_id": "demo", - "package": "skill-context-keeper", + "package": "skill-context-packet", "scenario_type": "positive", "should_trigger": "yes", - "user_prompt": "Refresh state", - "expected_artifacts": "assets/TASK_STATE.template.md", - "expected_events": "context:reload", + "user_prompt": "Compress the next root turn into a packet.", + "expected_artifacts": "root/packet", + "expected_events": "packet:compose", "notes": "optional guardrails", "max_commands": "3", "max_verbosity": "low", @@ -155,8 +176,8 @@ def test_positive_case_requires_trigger_cues_to_pass(self): "scenario_type": "positive", "should_trigger": "yes", "user_prompt": "Please answer this one-off punctuation question in the README and do nothing else.", - "expected_artifacts": "state/context.snapshot", - "expected_events": "context:reload", + "expected_artifacts": "root/task_state", + "expected_events": "root:refresh|root:reconcile|root:compress", "notes": "should fail if routing ignores polarity", } ], @@ -183,7 +204,7 @@ def test_negative_case_requires_suppress_cues_to_block_routing(self): "package": "skill-handoff-summary", "scenario_type": "negative", "should_trigger": "no", - "user_prompt": "Please write a handoff with blockers and next steps for the pause.", + "user_prompt": "Please write a root handoff with blockers and next steps for the pause.", "expected_artifacts": "none", "expected_events": "handoff:skip|direct:answer", "notes": "should fail if negative polarity is ignored", @@ -209,12 +230,12 @@ def test_expected_events_must_match_package_namespace(self): [ { "case_id": "bad_events", - "package": "skill-phase-gate", + "package": "skill-context-packet", "scenario_type": "positive", "should_trigger": "yes", - "user_prompt": "We need to split this multi-step refactor into phases before coding.", - "expected_artifacts": "plan/phase.plan", - "expected_events": "context:reload", + "user_prompt": "Compress the next root turn into a packet and keep it minimal.", + "expected_artifacts": "root/packet", + "expected_events": "root:refresh", "notes": "should fail if expected events are not scored", } ], @@ -241,9 +262,9 @@ def test_unmapped_expected_artifacts_fail_strict_mapping(self): "package": "skill-handoff-summary", "scenario_type": "positive", "should_trigger": "yes", - "user_prompt": "I need to stop for today; please write a handoff with blockers and next steps.", - "expected_artifacts": "handoff/HANDOFF.md|handoff/missing.md", - "expected_events": "handoff:capture", + "user_prompt": "I need to stop for today; please write a subtask handoff with blockers and next steps.", + "expected_artifacts": "subtask/handoff|subtask/missing", + "expected_events": "handoff:capture|handoff:pause|handoff:resume", "notes": "should fail if unmapped artifact tokens are ignored", } ], @@ -267,7 +288,9 @@ def test_routing_quality_fails_when_trigger_docs_are_missing(self): for relative in ["README.md", "README.zh-CN.md", "SKILL.md"]: path = package_root / relative text = path.read_text(encoding="utf-8") - for index, cue in enumerate(module.PACKAGE_RULES["skill-context-keeper"]["trigger_cues"]): + for index, cue in enumerate( + module.PACKAGE_RULES["skill-context-keeper"]["trigger_cues"] + ): text = re.sub( re.escape(cue), f"REMOVED_TRIGGER_{index}", @@ -281,13 +304,13 @@ def test_routing_quality_fails_when_trigger_docs_are_missing(self): csv_path, [ { - "case_id": "context_resume", + "case_id": "root_state_refresh", "package": "skill-context-keeper", "scenario_type": "positive", "should_trigger": "yes", - "user_prompt": "We’ve been iterating for a while; please resume from the last known state, summarize what changed, and carry forward unresolved TODOs.", - "expected_artifacts": "state/context.snapshot|state/continuity.note", - "expected_events": "context:reload|context:reconstruct|context:summary", + "user_prompt": "Rebuild the current root task picture from the repo and update .agent-state/root/TASK_STATE.md.", + "expected_artifacts": "root/task_state", + "expected_events": "root:refresh|root:reconcile|root:compress", "notes": "trigger docs should be required", } ], @@ -295,7 +318,7 @@ def test_routing_quality_fails_when_trigger_docs_are_missing(self): report = module.run_evaluations(repo_root, csv_path) - case = next(item for item in report["cases"] if item["case_id"] == "context_resume") + case = next(item for item in report["cases"] if item["case_id"] == "root_state_refresh") self.assertEqual(report["summary"]["failed"], 1) self.assertEqual(case["dimensions"]["routing_quality"]["status"], "fail") self.assertIn("routing docs", case["dimensions"]["routing_quality"]["reason"]) @@ -314,8 +337,8 @@ def test_workflow_completeness_rejects_bogus_same_namespace_token(self): "package": "skill-phase-gate", "scenario_type": "positive", "should_trigger": "yes", - "user_prompt": "We need to split this multi-step refactor into phases before coding.", - "expected_artifacts": "plan/phase.plan", + "user_prompt": "Run a checkpoint before and after this risky multi-file refactor.", + "expected_artifacts": "phase/preflight", "expected_events": "phase:anything", "notes": "should fail when same-namespace nonsense tokens are used", } @@ -343,9 +366,9 @@ def test_guardrails_fail_when_invalid_metadata_values_are_present(self): "package": "skill-task-continuity", "scenario_type": "positive", "should_trigger": "yes", - "user_prompt": "Set up the long-task continuity suite and coordinate the context keeper, phase gate, and handoff packages.", - "expected_artifacts": "AGENTS.md", - "expected_events": "bootstrap:agents_md", + "user_prompt": "Bootstrap the context protocol and route me to the right atomic skill.", + "expected_artifacts": "suite/agents|suite/index", + "expected_events": "suite:bootstrap|suite:route|suite:explain", "notes": "invalid guardrail metadata should fail", "max_commands": "0", "max_verbosity": "extreme", diff --git a/skills/README.md b/skills/README.md index 6a9a25f..ae4b0d9 100644 --- a/skills/README.md +++ b/skills/README.md @@ -10,6 +10,10 @@ Use this quick guide first: - I paused a task and need to rebuild the current picture. Start with `skill-context-keeper`. +- I am splitting work into a bounded child task with its own local context. + Start with `skill-subtask-context`. +- I need the smallest possible context object for the next turn. + Start with `skill-context-packet`. - 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. @@ -29,10 +33,12 @@ Use this quick guide first: | Skill | Best For | Docs | | --- | --- | --- | | `skill-governance` | Governing Codex skill assets with add, enable, doctor, repair, audit, and document tasks | [EN](skill-governance/README.md) / [中文](skill-governance/README.zh-CN.md) | -| `skill-context-keeper` | Refreshing current task state without taking over checkpoints or handoffs | [EN](skill-context-keeper/README.md) / [中文](skill-context-keeper/README.zh-CN.md) | -| `skill-phase-gate` | Adding preflight and postflight checkpoints around substantial edits | [EN](skill-phase-gate/README.md) / [中文](skill-phase-gate/README.zh-CN.md) | -| `skill-handoff-summary` | Producing compact continuation handoffs with status, blockers, and exact next steps | [EN](skill-handoff-summary/README.md) / [中文](skill-handoff-summary/README.zh-CN.md) | -| `skill-task-continuity` | Bootstrapping and composing the continuity suite while preserving atomic package boundaries | [EN](skill-task-continuity/README.md) / [中文](skill-task-continuity/README.zh-CN.md) | +| `skill-context-keeper` | Refreshing and compressing trusted root-task state without taking over child-task state or handoffs | [EN](skill-context-keeper/README.md) / [中文](skill-context-keeper/README.zh-CN.md) | +| `skill-subtask-context` | Opening, refreshing, and closing child-task state without bloating root task context | [EN](skill-subtask-context/README.md) / [中文](skill-subtask-context/README.zh-CN.md) | +| `skill-context-packet` | Compressing the minimum context needed for the next root or subtask turn | [EN](skill-context-packet/README.md) / [中文](skill-context-packet/README.zh-CN.md) | +| `skill-phase-gate` | Adding optional operational checkpoints around risky edits without taking over state ownership | [EN](skill-phase-gate/README.md) / [中文](skill-phase-gate/README.zh-CN.md) | +| `skill-handoff-summary` | Producing compact continuation handoffs for root tasks or subtasks with status, blockers, and exact next steps | [EN](skill-handoff-summary/README.md) / [中文](skill-handoff-summary/README.zh-CN.md) | +| `skill-task-continuity` | Bootstrapping `INDEX.md`, root packets, subtask folders, and suite composition guidance | [EN](skill-task-continuity/README.md) / [中文](skill-task-continuity/README.zh-CN.md) | ## Package Conventions @@ -40,4 +46,4 @@ Use this quick guide first: - The directory name should match the `name` field in `SKILL.md`. - Package `README.md` files are the main entry point for users. - `references/` is for reader-facing material; `docs/` is for maintainer notes when needed. -- For the long-task continuity workflow, start with `skill-task-continuity` only when you need suite bootstrap or composition guidance; otherwise install the atomic package that owns the next action. +- For the long-task continuity workflow, start with `skill-task-continuity` only when you need suite bootstrap or composition guidance; otherwise install the atomic package that owns the next action or the packet you need next. diff --git a/skills/README.zh-CN.md b/skills/README.zh-CN.md index bf0762d..1f12526 100644 --- a/skills/README.zh-CN.md +++ b/skills/README.zh-CN.md @@ -10,6 +10,10 @@ - 我暂停了一个任务，现在需要重新拼出当前图景。 先用 `skill-context-keeper`。 +- 我需要把工作拆成一个边界清楚、独立维护的子任务。 + 先用 `skill-subtask-context`。 +- 我需要为下一轮只准备最小必要上下文。 + 先用 `skill-context-packet`。 - 我马上要做一个高风险或多文件改动。 先用 `skill-phase-gate`。 - 我现在要停下来，并留下一个可以直接续做的重启说明。 @@ -29,10 +33,12 @@ | Skill | 适用场景 | 文档 | | --- | --- | --- | | `skill-governance` | 用任务式入口治理 skill 资产，包括新增、启用、体检、修复、审计和补文档 | [EN](skill-governance/README.md) / [中文](skill-governance/README.zh-CN.md) | -| `skill-context-keeper` | 刷新当前任务状态，但不接管检查点或交接职责 | [EN](skill-context-keeper/README.md) / [中文](skill-context-keeper/README.zh-CN.md) | -| `skill-phase-gate` | 在较大改动前后增加 preflight / postflight 检查点 | [EN](skill-phase-gate/README.md) / [中文](skill-phase-gate/README.zh-CN.md) | -| `skill-handoff-summary` | 生成紧凑、面向续做的交接摘要，保留状态、阻塞点和下一步 | [EN](skill-handoff-summary/README.md) / [中文](skill-handoff-summary/README.zh-CN.md) | -| `skill-task-continuity` | 在保持原子包边界的前提下启动并组合连续性套件 | [EN](skill-task-continuity/README.md) / [中文](skill-task-continuity/README.zh-CN.md) | +| `skill-context-keeper` | 刷新并压缩可信的 root 任务状态，但不接管子任务状态或 handoff | [EN](skill-context-keeper/README.md) / [中文](skill-context-keeper/README.zh-CN.md) | +| `skill-subtask-context` | 为子任务建立、刷新和关闭局部状态，避免根任务上下文膨胀 | [EN](skill-subtask-context/README.md) / [中文](skill-subtask-context/README.zh-CN.md) | +| `skill-context-packet` | 把下一轮真正需要的上下文压缩成最小注入对象 | [EN](skill-context-packet/README.md) / [中文](skill-context-packet/README.zh-CN.md) | +| `skill-phase-gate` | 在 risky edits 前后增加可选的 operational checkpoint，但不接管状态归属 | [EN](skill-phase-gate/README.md) / [中文](skill-phase-gate/README.zh-CN.md) | +| `skill-handoff-summary` | 为 root 任务或子任务生成紧凑、面向续做的交接摘要，保留状态、阻塞点和下一步 | [EN](skill-handoff-summary/README.md) / [中文](skill-handoff-summary/README.zh-CN.md) | +| `skill-task-continuity` | 启动 `INDEX.md`、root packet、subtask 目录和整套连续性组合说明 | [EN](skill-task-continuity/README.md) / [中文](skill-task-continuity/README.zh-CN.md) | ## 包结构约定 @@ -40,4 +46,4 @@ - 目录名应与 `SKILL.md` 中的 `name` 字段保持一致。 - 包内 `README.md` 是给使用者最主要的入口。 - `references/` 主要放读者资料，`docs/` 主要放维护者说明。 -- 对长任务连续性流程来说，只有在需要套件级启动或组合说明时才从 `skill-task-continuity` 开始；如果只需要某个具体动作，直接安装对应的原子包。 +- 对长任务连续性流程来说，只有在需要套件级启动或组合说明时才从 `skill-task-continuity` 开始；如果只需要某个具体动作，直接安装对应的原子包或 packet 工具。 diff --git a/skills/skill-context-keeper/README.md b/skills/skill-context-keeper/README.md index 24e4a32..4a07132 100644 --- a/skills/skill-context-keeper/README.md +++ b/skills/skill-context-keeper/README.md @@ -4,53 +4,58 @@ ## Overview -`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. +`skill-context-keeper` is the focused package for root-state refresh and compression during long-running coding work. +Use it when the root task is still ongoing, but the trusted root picture is stale, noisy, or too bloated to keep injecting directly. ## Start Here In 30 Seconds -- 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`. +- Use this when: the root task is still active, but the current picture is stale, scattered, or too large to keep as-is. +- You'll get: a compact, verified root-task snapshot that separates facts, assumptions, decisions, risks, and next actions. +- Typical output: updates `.agent-state/root/TASK_STATE.md`. If you want to tell Codex exactly what to do: Try this first: -- `Use skill-context-keeper to refresh the current task state from the repository before we continue.` +- `Use skill-context-keeper to refresh the root task state from the repository before we continue.` ## Install 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.` +- `Use skill-installer to install skill-context-keeper from Golden-Promise/codex-skill-library at skills/skill-context-keeper using ref .` If you want the exact shell command, jump to [Install Details](#install-details). ## What File Will This Create Or Update? -The typical downstream file is `.agent-state/TASK_STATE.md`. +The typical downstream file is `.agent-state/root/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: +Use this package when you want to refresh or rewrite that root task-state file so the next turn can resume from a trusted summary of: - the current objective - current repository facts - completed work - open issues and risks +- compression or archive notes for stale detail - the next recommended action ## Don't Use This When - you need a preflight or postflight checkpoint around a risky change +- you need a bounded child task with its own local state +- you need packet compression instead of a full root-state refresh - 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 -This package does not own workflow gating and does not own final handoffs. +This package owns root-state refresh and compression, does not own subtask state, does not own workflow gating, and does not own final handoffs. ## Related Skills +- `skill-subtask-context` for `.agent-state/subtasks//TASK_STATE.md` +- `skill-context-packet` for packet-sized context injection - `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 @@ -72,5 +77,5 @@ Replace `/path/to/install-skill-from-github.py` with the actual path to your loc python3 /path/to/install-skill-from-github.py \ --repo Golden-Promise/codex-skill-library \ --path skills/skill-context-keeper \ - --ref v0.6.1 + --ref ``` diff --git a/skills/skill-context-keeper/README.zh-CN.md b/skills/skill-context-keeper/README.zh-CN.md index e3fde48..a494ab9 100644 --- a/skills/skill-context-keeper/README.zh-CN.md +++ b/skills/skill-context-keeper/README.zh-CN.md @@ -4,53 +4,58 @@ ## 概述 -`skill-context-keeper` 是一个专注型包，用于在长时间编码任务中刷新结构化任务状态。 -当任务还没结束，但你手上的任务图景已经变旧、变散或不再完全可信时，就该用它。 +`skill-context-keeper` 是一个专注型包，用于做 root-state refresh 和 compression。 +当根任务还没结束，但你手上的 root task 图景已经变旧、变散，或者已经膨胀到不适合继续直接注入时，就该用它。 ## 30 秒快速开始 -- 什么时候用：任务仍在继续，但当前上下文已经陈旧、分散，或者可信度不够。 -- 你会得到什么：一个紧凑、可信的任务快照，把事实、假设、决策、风险和下一步动作分清楚。 -- 典型产物：更新 `.agent-state/TASK_STATE.md`。 +- 什么时候用：根任务仍在继续，但当前图景已经陈旧、分散，或者已经大到不适合原样继续用。 +- 你会得到什么：一个紧凑、可信的根任务快照，把事实、假设、决策、风险和下一步动作分清楚。 +- 典型产物：更新 `.agent-state/root/TASK_STATE.md`。 如果你想直接告诉 Codex 怎么做： 先这样对 Codex 说： -- `请用 skill-context-keeper 根据仓库现状刷新当前任务状态。` +- `请用 skill-context-keeper 根据仓库现状刷新根任务状态。` ## 安装 你可以直接这样对 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。` +- `请用 skill-installer 从 Golden-Promise/codex-skill-library 的 skills/skill-context-keeper 安装 skill-context-keeper，并使用 ref 。` 如果你想看精确的 shell 命令，可以直接跳到后面的 [安装细节](#安装细节)。 ## 会创建或更新什么文件？ -最典型的下游文件是 `.agent-state/TASK_STATE.md`。 +最典型的下游文件是 `.agent-state/root/TASK_STATE.md`。 -当你希望刷新或重写这个任务状态文件，让下一轮可以从一个可信摘要继续时，就该用这个包。它通常会帮助你整理： +当你希望刷新或重写这个 root 任务状态文件，让下一轮可以从一个可信摘要继续时，就该用这个包。它通常会帮助你整理： - 当前目标 - 仓库里的已验证事实 - 已完成工作 - 开放问题和风险 +- 需要压缩或归档的陈旧细节 - 下一步推荐动作 ## 不适合什么时候用 - 你需要为高风险改动加 preflight 或 postflight 检查点 +- 你需要一个拥有独立局部状态的子任务 +- 你需要 packet compression，而不是完整 root 状态刷新 - 你需要写一份可交接、可暂停的 handoff - 你是第一次在仓库里搭建整套连续性工作流 - 你想要的是泛化的流程控制，而不是状态刷新 -这个包不负责 workflow gating，也不负责 final handoffs。 +这个包负责 root-state refresh 和 compression，不负责 subtask state，不负责 workflow gating，也不负责 final handoffs。 ## 相关技能 +- `skill-subtask-context`：适合处理 `.agent-state/subtasks//TASK_STATE.md` +- `skill-context-packet`：适合 packet-sized context 注入 - `skill-phase-gate`：适合高价值的 preflight / postflight 检查点 - `skill-handoff-summary`：适合暂停或转交时写 handoff - `skill-task-continuity`：适合第一次搭建整套连续性流程 @@ -72,5 +77,5 @@ python3 /path/to/install-skill-from-github.py \ --repo Golden-Promise/codex-skill-library \ --path skills/skill-context-keeper \ - --ref v0.6.1 + --ref ``` diff --git a/skills/skill-context-keeper/SKILL.md b/skills/skill-context-keeper/SKILL.md index 5bc4d00..37c2057 100644 --- a/skills/skill-context-keeper/SKILL.md +++ b/skills/skill-context-keeper/SKILL.md @@ -1,41 +1,44 @@ --- name: skill-context-keeper -description: Use when the user needs to preserve or refresh structured long-task state for an ongoing coding task without running workflow gates or generating a final handoff. +description: Use when the user needs to refresh or compress trusted root-task state for an ongoing coding task without creating subtask-local state, workflow gates, or final handoffs. --- # Skill Context Keeper ## Overview -Maintain structured working state for long-running coding tasks. -Use this skill when the thread needs trustworthy context reconstruction or a refreshed task-state artifact such as `.agent-state/TASK_STATE.md`, not phase planning or final transfer notes. +Maintain trusted root-task state for long-running coding tasks. +Use this skill when the thread needs root-state refresh or compression for an artifact such as `.agent-state/root/TASK_STATE.md`, not subtask-local state, packet compression, phase gates, or final transfer notes. ## Use This Skill When -- resuming a task after an interruption, stale summary, or context loss -- rebuilding the last known task state before new work continues -- refreshing TODOs, verified facts, decisions, or working assumptions for an ongoing task -- reconciling what changed since the last stable checkpoint -- updating a downstream state file such as `.agent-state/TASK_STATE.md` +- resuming a task after an interruption, stale summary, or context loss at the root-task level +- rebuilding the last known root task state before new work continues +- refreshing verified facts, decisions, assumptions, or next actions in `.agent-state/root/TASK_STATE.md` +- compressing stale root-task detail into archive-minded notes instead of letting the active summary grow indefinitely +- reconciling root-state changes since the last stable checkpoint ## Do Not Use This Skill When +- the user needs a bounded child task with its own local state +- the next step only needs a packet-sized context object - the user needs workflow phases, checkpoints, or exit criteria -- the task is about deciding whether work should be gated before implementation - the thread needs a final pause summary or transfer handoff - the request is asking one package to coordinate the full continuity suite ## Core Rules -1. Keep the output focused on current task state, not future workflow control. +1. Keep the output focused on root-state refresh and compression, not future workflow control. 2. Distinguish verified facts from assumptions and from decisions already made. -3. Assume downstream path examples such as `.agent-state/TASK_STATE.md` unless the user specifies another target. -4. Do not run phase gates. -5. Do not generate final handoffs. +3. Assume downstream path examples such as `.agent-state/root/TASK_STATE.md` unless the user specifies another target. +4. Move stale detail into compression or archive notes instead of inflating the active summary. +5. Do not create subtask-local state. +6. Do not run phase gates. +7. Do not generate final handoffs. ## References - `README.md` and `README.zh-CN.md`: package overview, installation, and boundary guidance - `references/use-cases.md` and `references/use-cases.zh-CN.md`: reader-facing trigger examples -- `references/prompt-templates.en.md` and `references/prompt-templates.zh-CN.md`: reusable refresh prompts -- `assets/TASK_STATE.template.md`: compact task-state artifact template +- `references/prompt-templates.en.md` and `references/prompt-templates.zh-CN.md`: reusable root-state refresh prompts +- `assets/TASK_STATE.template.md`: compact root task-state artifact template diff --git a/skills/skill-context-keeper/agents/openai.yaml b/skills/skill-context-keeper/agents/openai.yaml index d8f3cbe..389e18f 100644 --- a/skills/skill-context-keeper/agents/openai.yaml +++ b/skills/skill-context-keeper/agents/openai.yaml @@ -1,4 +1,4 @@ interface: display_name: "Skill Context Keeper" - short_description: "Maintain structured long-task state without taking over workflow gates or final handoffs" - default_prompt: "Use $skill-context-keeper when the task needs a reliable long-thread state refresh: reconstruct the current context, keep facts separate from assumptions and decisions, update a downstream artifact such as .agent-state/TASK_STATE.md when requested, and keep the output focused on ongoing task state rather than phase gates or final handoff notes." + short_description: "Maintain trusted root-task state without taking over subtask state, packets, gates, or handoffs" + default_prompt: "Use $skill-context-keeper when the task needs a reliable root-state refresh: reconstruct the current root task context, keep facts separate from assumptions and decisions, update a downstream artifact such as .agent-state/root/TASK_STATE.md, capture compression or archive notes when stale detail should move out of the active summary, and avoid taking over subtask-local state, packet compression, phase gates, or final handoff notes." diff --git a/skills/skill-context-keeper/assets/TASK_STATE.template.md b/skills/skill-context-keeper/assets/TASK_STATE.template.md index 0362343..9157bbd 100644 --- a/skills/skill-context-keeper/assets/TASK_STATE.template.md +++ b/skills/skill-context-keeper/assets/TASK_STATE.template.md @@ -36,6 +36,10 @@ - Capture decisions with a short reason. - Separate decisions from open options. +## Compression / Archive Notes +- List stale detail that should move out of active root state. +- Point to archive paths or packet updates instead of pasting long history here. + ## Resume Checklist - Give a short restart checklist in execution order. - End with the first command, file, or prompt to use next. diff --git a/skills/skill-context-keeper/references/prompt-templates.en.md b/skills/skill-context-keeper/references/prompt-templates.en.md index f75d781..156fd2e 100644 --- a/skills/skill-context-keeper/references/prompt-templates.en.md +++ b/skills/skill-context-keeper/references/prompt-templates.en.md @@ -1,16 +1,19 @@ # skill-context-keeper Prompt Templates -Use these templates when you want `skill-context-keeper` to refresh structured long-task state without drifting into workflow gating or final handoffs. +Use these templates when you want `skill-context-keeper` to refresh or compress trusted root-task state without drifting into subtask-local state, packet compression, workflow gating, or final handoffs. ## Positive Trigger Prompts -- `Use skill-context-keeper to refresh the current task state from the repository before we continue.` -- `Reconcile the existing summary with the codebase and rewrite .agent-state/TASK_STATE.md.` -- `Refresh the current task state, keep facts separate from assumptions, and list the next recommended action.` +- `Use skill-context-keeper to refresh the root task state from the repository before we continue.` +- `Reconcile the existing root summary with the codebase and rewrite .agent-state/root/TASK_STATE.md.` +- `Refresh the root task state, keep facts separate from assumptions, and list the next recommended action.` +- `Compress stale root-state detail into archive notes while preserving active facts.` ## Negative Trigger Prompts - `Decide the project phases and gate the work before implementation starts.` +- `Open a child task with its own local state.` +- `Compress the next turn into a packet instead of refreshing full root state.` - `Generate the final handoff note for the next agent and close out the thread.` - `Handle planning, state refresh, and the final transfer as one combined workflow.` @@ -19,20 +22,21 @@ Use these templates when you want `skill-context-keeper` to refresh structured l Use this phrasing when you want a straightforward state refresh: ```text -Use skill-context-keeper to refresh the current task state. +Use skill-context-keeper to refresh the root task state. Check the repository, keep verified facts separate from assumptions and decisions, -update .agent-state/TASK_STATE.md, and end with the next recommended action plus verification still needed. -Do not add workflow gates or a final handoff. +update .agent-state/root/TASK_STATE.md, add compression or archive notes if stale detail should move out of active state, +and end with the next recommended action plus verification still needed. +Do not add subtask-local state, packet compression, workflow gates, or a final handoff. ``` ## Compact Resume Prompt ```text -Refresh the current task state for this long-running coding task. -Assume the downstream artifact lives at .agent-state/TASK_STATE.md. +Refresh the root task state for this long-running coding task. +Assume the downstream artifact lives at .agent-state/root/TASK_STATE.md. Capture current objective, scope, hard constraints, verified codebase facts, -completed work, open risks, recent decisions, and the next recommended action. -Keep the package boundary narrow: state maintenance only. +completed work, open risks, recent decisions, compression / archive notes, and the next recommended action. +Keep the package boundary narrow: root-state refresh and compression only. ``` ## Facts, Assumptions, and Decisions Prompt @@ -40,5 +44,5 @@ Keep the package boundary narrow: state maintenance only. ```text Rebuild the task state and explicitly label each item as Fact, Assumption, or Decision. Use repository evidence for facts, keep assumptions short, and record only decisions that are already made. -Write the refreshed state to .agent-state/TASK_STATE.md without generating a phase gate or final handoff. +Write the refreshed state to .agent-state/root/TASK_STATE.md without creating subtask-local state, a packet, a phase gate, or a final handoff. ``` diff --git a/skills/skill-context-keeper/references/prompt-templates.zh-CN.md b/skills/skill-context-keeper/references/prompt-templates.zh-CN.md index 47a2084..72e436a 100644 --- a/skills/skill-context-keeper/references/prompt-templates.zh-CN.md +++ b/skills/skill-context-keeper/references/prompt-templates.zh-CN.md @@ -1,16 +1,19 @@ # skill-context-keeper 提示词模板 -当你希望 `skill-context-keeper` 刷新结构化长任务状态，而且不要偏离到流程门控或最终交接时，可直接复用下面这些模板。 +当你希望 `skill-context-keeper` 刷新或压缩可信的 root task state，而且不要偏离到 subtask local state、packet compression、流程门控或最终交接时，可直接复用下面这些模板。 ## Positive Trigger Prompts -- `请使用 skill-context-keeper 在继续之前根据仓库刷新当前任务状态。` -- `请把现有摘要与代码库现状对齐，并重写 .agent-state/TASK_STATE.md。` -- `刷新当前任务状态，明确区分事实、假设和决策，并给出推荐的下一步动作。` +- `请使用 skill-context-keeper 在继续之前根据仓库刷新根任务状态。` +- `请把现有根任务摘要与代码库现状对齐，并重写 .agent-state/root/TASK_STATE.md。` +- `刷新根任务状态，明确区分事实、假设和决策，并给出推荐的下一步动作。` +- `把根任务里已经陈旧的细节压进 archive notes，但保留仍然活跃的事实。` ## Negative Trigger Prompts - `先决定项目阶段，并在实现前设置阶段门。` +- `为某个子任务打开独立的局部状态。` +- `把下一轮压成一个 packet，而不是刷新完整 root 状态。` - `为下一位代理生成最终交接说明，并结束这个线程。` - `把规划、状态刷新和最终转交流程合并成一个整体工作流来处理。` @@ -19,19 +22,20 @@ 当你想直接表达“刷新状态”时，可以这样说： ```text -请使用 skill-context-keeper 刷新当前任务状态。 +请使用 skill-context-keeper 刷新根任务状态。 检查仓库，把已验证事实与假设、决策分开， -更新 .agent-state/TASK_STATE.md，并在结尾写出推荐的下一步动作和仍需完成的验证。 -不要加入流程门控，也不要生成最终交接。 +更新 .agent-state/root/TASK_STATE.md，并在需要时补上 compression / archive notes， +最后写出推荐的下一步动作和仍需完成的验证。 +不要创建 subtask state，不要压 packet，也不要加入流程门控或最终交接。 ``` ## 紧凑续做模板 ```text -请刷新这个长编码任务的当前状态。 -假设下游状态文件路径是 .agent-state/TASK_STATE.md。 -记录当前目标、范围、硬约束、已验证代码库事实、已完成工作、开放风险、最近决策，以及推荐的下一步动作。 -保持包边界收敛：只做状态维护。 +请刷新这个长编码任务的根任务状态。 +假设下游状态文件路径是 .agent-state/root/TASK_STATE.md。 +记录当前目标、范围、硬约束、已验证代码库事实、已完成工作、开放风险、最近决策、compression / archive notes，以及推荐的下一步动作。 +保持包边界收敛：只做 root-state refresh 和 compression。 ``` ## 事实 / 假设 / 决策模板 @@ -39,5 +43,5 @@ ```text 请重建任务状态，并把每一项明确标注为 Fact、Assumption 或 Decision。 事实必须来自仓库证据，假设保持简短，只记录已经做出的决策。 -将刷新后的状态写入 .agent-state/TASK_STATE.md，不要生成阶段门控或最终交接。 +将刷新后的状态写入 .agent-state/root/TASK_STATE.md，不要创建 subtask state，不要生成 packet、阶段门控或最终交接。 ``` diff --git a/skills/skill-context-keeper/references/use-cases.md b/skills/skill-context-keeper/references/use-cases.md index acab71e..668e098 100644 --- a/skills/skill-context-keeper/references/use-cases.md +++ b/skills/skill-context-keeper/references/use-cases.md @@ -1,19 +1,21 @@ # skill-context-keeper Use Cases -`skill-context-keeper` is for maintaining structured long-task state while work is still in progress. -Use it when the thread needs a reliable refresh of the current task picture, not when it needs staged workflow control or a final handoff. +`skill-context-keeper` is for maintaining trusted root-task state while work is still in progress. +Use it when the thread needs a reliable refresh of the root task picture or a root-state compression pass, not when it needs subtask-local state, packet compression, staged workflow control, or a final handoff. ## Positive Trigger Prompts -- `Use skill-context-keeper to refresh the current task state before we continue coding.` -- `Rebuild the current task picture from the repo and update .agent-state/TASK_STATE.md.` -- `The summary is stale. Reconstruct facts, open risks, and the next action for this task.` -- `Refresh the current task state and carry forward unresolved work without making a handoff note.` -- `Before we continue, update the structured state file at .agent-state/TASK_STATE.md with verified codebase facts.` +- `Use skill-context-keeper to refresh the root task state before we continue coding.` +- `Rebuild the current root task picture from the repo and update .agent-state/root/TASK_STATE.md.` +- `The root summary is stale. Reconstruct facts, open risks, and the next action for this task.` +- `Refresh the root task state and carry forward unresolved work without making a handoff note.` +- `Before we continue, update .agent-state/root/TASK_STATE.md with verified codebase facts and compression notes.` ## Negative Trigger Prompts - `Split this migration into phases with checkpoints before we start implementation.` +- `Open a child task with its own local state for the parser cleanup.` +- `Compress the next turn into a small packet instead of rewriting full state.` - `Write the final handoff summary for the next agent taking over this task.` - `Create a release checklist and decide which phase gate we need to pass next.` - `Prepare the final user-facing completion note and wrap up the task.` @@ -23,24 +25,26 @@ Use it when the thread needs a reliable refresh of the current task picture, not Use wording like this when the request is specifically about refreshing state: -- `Refresh the current task state.` -- `Update the working state snapshot for this task.` -- `Reconcile the current summary with the repository and rewrite the task state file.` -- `Bring .agent-state/TASK_STATE.md up to date before more implementation.` +- `Refresh the root task state.` +- `Update the working root-state snapshot for this task.` +- `Reconcile the current root summary with the repository and rewrite the task-state file.` +- `Bring .agent-state/root/TASK_STATE.md up to date before more implementation.` +- `Compress stale root-state detail into archive notes while preserving active facts.` ## Facts vs Assumptions vs Decisions Example -Example for `.agent-state/TASK_STATE.md`: +Example for `.agent-state/root/TASK_STATE.md`: - Fact: `tests/test_package_contract.py` exists and currently checks for trigger sections in both use-case references. -- Assumption: The next agent will continue using `.agent-state/TASK_STATE.md` as the downstream path because the package examples point there. -- Decision: Keep this package focused on state maintenance only, so phase gates and final handoffs stay in sibling packages. +- Assumption: The next agent will continue using `.agent-state/root/TASK_STATE.md` as the downstream path because the package examples point there. +- Decision: Keep this package focused on root-state refresh and compression only, so subtask state, packets, phase gates, and handoffs stay in sibling packages. ## Typical Output Shape -The package usually refreshes a compact state artifact such as `.agent-state/TASK_STATE.md` with: +The package usually refreshes a compact state artifact such as `.agent-state/root/TASK_STATE.md` with: - verified facts from the codebase - unresolved risks and open questions +- compression or archive notes for stale detail - the next recommended action - verification still needed before claiming completion diff --git a/skills/skill-context-keeper/references/use-cases.zh-CN.md b/skills/skill-context-keeper/references/use-cases.zh-CN.md index 7d2240e..8bfc8d8 100644 --- a/skills/skill-context-keeper/references/use-cases.zh-CN.md +++ b/skills/skill-context-keeper/references/use-cases.zh-CN.md @@ -1,19 +1,21 @@ # skill-context-keeper 使用场景 -`skill-context-keeper` 只负责维护长任务进行中的结构化状态。 -当线程需要可靠地刷新“当前任务图景”时使用它；如果需求是阶段门控或最终交接，就不该由这个包接管。 +`skill-context-keeper` 只负责维护可信的 root task state。 +当线程需要可靠地刷新根任务图景，或者需要对 root 状态做 compression 时使用它；如果需求是 subtask local state、packet compression、阶段门控或最终交接，就不该由这个包接管。 ## 适用触发示例 -- `请使用 skill-context-keeper 刷新当前任务状态，然后我们再继续编码。` -- `根据仓库现状重建当前任务图景，并更新 .agent-state/TASK_STATE.md。` -- `现在的摘要已经过时了，请重建事实、未决风险和下一步动作。` -- `刷新当前任务状态，并延续未完成工作，但不要写成交接说明。` -- `继续实现前，请先把 .agent-state/TASK_STATE.md 更新为包含已验证代码库事实的版本。` +- `请使用 skill-context-keeper 刷新根任务状态，然后我们再继续编码。` +- `根据仓库现状重建当前根任务图景，并更新 .agent-state/root/TASK_STATE.md。` +- `现在的根任务摘要已经过时了，请重建事实、未决风险和下一步动作。` +- `刷新根任务状态，并延续未完成工作，但不要写成交接说明。` +- `继续实现前，请先把 .agent-state/root/TASK_STATE.md 更新为包含已验证代码库事实和压缩备注的版本。` ## 不适用触发示例 - `在开始实现前，把这次迁移拆成带检查点的阶段计划。` +- `为 parser-cleanup 打开一个拥有独立局部状态的子任务。` +- `把下一轮压成一个很小的 packet，而不是重写整份状态。` - `为下一位接手任务的代理写一份最终交接摘要。` - `创建 release 检查清单，并决定下一个要通过的阶段门。` - `准备最终给用户的完成说明，并结束这个任务。` @@ -23,24 +25,26 @@ 如果请求的重点就是“刷新状态”，可以直接这样表达： -- `刷新当前任务状态。` -- `更新这个任务的工作状态快照。` -- `根据仓库现状对齐当前摘要，并重写任务状态文件。` -- `在继续实现前，把 .agent-state/TASK_STATE.md 刷新到最新。` +- `刷新根任务状态。` +- `更新这个任务的 root 状态快照。` +- `根据仓库现状对齐当前根任务摘要，并重写任务状态文件。` +- `在继续实现前，把 .agent-state/root/TASK_STATE.md 刷新到最新。` +- `把根任务里已经变旧的细节压进 archive notes，但保留活跃事实。` ## 事实 / 假设 / 决策示例 -以 `.agent-state/TASK_STATE.md` 为例： +以 `.agent-state/root/TASK_STATE.md` 为例： - Fact：`tests/test_package_contract.py` 已存在，并会检查两份 use-case 参考文档里都有触发与非触发章节。 -- Assumption：由于包内示例路径使用 `.agent-state/TASK_STATE.md`，下游代理会继续沿用这个状态文件位置。 -- Decision：这个包只负责状态维护，因此阶段门控和最终交接继续留给同套件中的兄弟包处理。 +- Assumption：由于包内示例路径使用 `.agent-state/root/TASK_STATE.md`，下游代理会继续沿用这个 root 状态文件位置。 +- Decision：这个包只负责 root-state refresh 和 compression，因此 subtask state、packet、阶段门控和最终交接继续留给同套件中的兄弟包处理。 ## 常见输出形态 -这个包通常会刷新一个紧凑的状态产物，例如 `.agent-state/TASK_STATE.md`，内容包括： +这个包通常会刷新一个紧凑的状态产物，例如 `.agent-state/root/TASK_STATE.md`，内容包括： - 来自代码库的已验证事实 - 未解决风险与开放问题 +- 需要压缩或归档的陈旧细节 - 推荐的下一步动作 - 在宣告完成前仍需补做的验证 diff --git a/skills/skill-context-keeper/tests/test_package_contract.py b/skills/skill-context-keeper/tests/test_package_contract.py index c17a39a..0c84862 100644 --- a/skills/skill-context-keeper/tests/test_package_contract.py +++ b/skills/skill-context-keeper/tests/test_package_contract.py @@ -29,6 +29,7 @@ def test_task_state_template_has_required_sections(self): "## Next Recommended Action", "## Verification Still Needed", "## Recent Decisions", + "## Compression / Archive Notes", "## Resume Checklist", ]: self.assertIn(heading, text) @@ -44,14 +45,16 @@ def test_chinese_use_cases_include_trigger_sections(self): self.assertRegex(text, r"(?m)^## +不适用触发示例$") def test_readme_spells_out_package_boundary(self): - text = (ROOT / "README.md").read_text(encoding="utf-8") - self.assertIn("does not own workflow gating", text) + text = (ROOT / "README.md").read_text(encoding="utf-8").lower() + self.assertIn("root-state refresh", text) + self.assertIn("compression", text) + self.assertIn("does not own subtask state", 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) + self.assertIn("use skill-context-keeper to refresh the root task state", text) def test_readme_has_fast_entry_sections(self): text = (ROOT / "README.md").read_text(encoding="utf-8") @@ -64,7 +67,7 @@ def test_readme_has_fast_entry_sections(self): ]: self.assertIn(heading, text) self.assertIn("Typical output:", text) - self.assertIn(".agent-state/TASK_STATE.md", text) + self.assertIn(".agent-state/root/TASK_STATE.md", text) self.assertIn("Try this first:", text) self.assertIn("Use skill-context-keeper", text) @@ -79,7 +82,7 @@ def test_chinese_readme_has_fast_entry_sections(self): ]: self.assertIn(heading, text) self.assertIn("典型产物：", text) - self.assertIn(".agent-state/TASK_STATE.md", text) + self.assertIn(".agent-state/root/TASK_STATE.md", text) self.assertIn("先这样对 Codex 说：", text) self.assertIn("请用 skill-context-keeper", text) diff --git a/skills/skill-context-packet/README.md b/skills/skill-context-packet/README.md new file mode 100644 index 0000000..aa572d9 --- /dev/null +++ b/skills/skill-context-packet/README.md @@ -0,0 +1,78 @@ +# skill-context-packet + +[简体中文](README.zh-CN.md) + +## Overview + +`skill-context-packet` is the narrow package for writing the minimum context object needed for the next root or subtask turn. +Use it when a full state file would waste context budget and the next step only needs a compact execution packet. + +## Start Here In 30 Seconds + +- Use this when: the next turn needs the smallest useful context object instead of a full state refresh. +- You'll get: a packet with the exact objective, scope, inputs, facts, constraints, risks, exit criteria, and next command. +- Typical output: updates `.agent-state/root/PACKET.md` or `.agent-state/subtasks//PACKET.md`. + +If you want to tell Codex exactly what to do: + +Try this first: + +- `Use skill-context-packet to compress the next turn into .agent-state/root/PACKET.md and keep only the minimum facts and constraints we still need.` + +## Install + +You can ask Codex in natural language: + +- `Use skill-installer to install skill-context-packet from Golden-Promise/codex-skill-library at skills/skill-context-packet.` +- `Use skill-installer to install skill-context-packet from Golden-Promise/codex-skill-library at skills/skill-context-packet using ref .` + +If you want the exact shell command, jump to [Install Details](#install-details). + +## What File Will This Create Or Update? + +The typical downstream files are `.agent-state/root/PACKET.md` and `.agent-state/subtasks//PACKET.md`. + +Use this package when you want to compress the next turn into a minimum context object that preserves: + +- the exact objective for this turn +- the narrow scope and explicit non-goals +- the minimal files or inputs worth loading +- the facts and constraints that still matter +- the exit criteria and exact next command + +## Don't Use This When + +- you need to rebuild root task state or subtask state in full +- you need a risky-change checkpoint or workflow gate +- you need a pause or transfer handoff +- you are bootstrapping the suite for the first time + +This package owns the minimum context object, does not own root task state, and does not own workflow gates. + +## Related Skills + +- `skill-context-keeper` for `.agent-state/root/TASK_STATE.md` +- `skill-subtask-context` for `.agent-state/subtasks//TASK_STATE.md` +- `skill-phase-gate` for meaningful preflight and postflight checkpoints +- `skill-handoff-summary` for pause and transfer notes +- `skill-task-continuity` for suite-level bootstrap and routing + +## Documentation + +- Trigger routing and package boundary: `SKILL.md` +- Use cases and trigger examples: [references/use-cases.md](references/use-cases.md) +- Chinese use cases: [references/use-cases.zh-CN.md](references/use-cases.zh-CN.md) +- 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) +- Packet template: [assets/PACKET.template.md](assets/PACKET.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-packet \ + --ref +``` diff --git a/skills/skill-context-packet/README.zh-CN.md b/skills/skill-context-packet/README.zh-CN.md new file mode 100644 index 0000000..7f170b9 --- /dev/null +++ b/skills/skill-context-packet/README.zh-CN.md @@ -0,0 +1,78 @@ +# skill-context-packet + +[English](README.md) + +## 概述 + +`skill-context-packet` 是一个窄边界包，专门负责为下一轮 root 或 subtask 生成“最小上下文对象”。 +当完整状态文件会浪费上下文预算，而下一步只需要一份紧凑执行包时，就用它。 + +## 30 秒快速开始 + +- 什么时候用：下一轮只需要最小可用上下文，而不需要整份状态刷新。 +- 你会得到什么：一份包含精确目标、范围、输入、事实、约束、风险、退出条件和下一条命令的 packet。 +- 典型产物：更新 `.agent-state/root/PACKET.md` 或 `.agent-state/subtasks//PACKET.md`。 + +如果你想直接告诉 Codex 怎么做： + +先这样对 Codex 说： + +- `请用 skill-context-packet 把下一轮压缩到 .agent-state/root/PACKET.md，只保留仍然必要的最小事实和约束。` + +## 安装 + +你可以直接用自然语言让 Codex 安装： + +- `请用 skill-installer 从 Golden-Promise/codex-skill-library 的 skills/skill-context-packet 安装 skill-context-packet。` +- `请用 skill-installer 从 Golden-Promise/codex-skill-library 的 skills/skill-context-packet 安装 skill-context-packet，并固定到 。` + +如果你想看精确的 shell 命令，可以直接跳到 [安装细节](#安装细节)。 + +## 会创建或更新什么文件？ + +典型的下游文件是 `.agent-state/root/PACKET.md` 和 `.agent-state/subtasks//PACKET.md`。 + +当你希望把下一轮压成一个 minimum context object 时，就使用这个包，保留： + +- 这一次的精确目标 +- 收敛后的范围和明确非目标 +- 真正值得加载的最小文件或输入 +- 仍然必须保留的事实和约束 +- 退出条件和下一条命令 + +## 不适合什么时候用 + +- 你需要完整重建 root task state 或 subtask state +- 你需要高风险改动前后的 workflow gate +- 你需要暂停或转交 handoff +- 你第一次在仓库里启动整套连续性工具链 + +这个包负责 minimum context object，不负责 root task state，也不负责 workflow gates。 + +## 相关技能 + +- `skill-context-keeper`：处理 `.agent-state/root/TASK_STATE.md` +- `skill-subtask-context`：处理 `.agent-state/subtasks//TASK_STATE.md` +- `skill-phase-gate`：处理 preflight / postflight 检查点 +- `skill-handoff-summary`：处理暂停和转交说明 +- `skill-task-continuity`：处理套件级 bootstrap 和路由 + +## 文档 + +- 触发路由与包边界：`SKILL.md` +- 用例与触发示例：[references/use-cases.zh-CN.md](references/use-cases.zh-CN.md) +- English use cases: [references/use-cases.md](references/use-cases.md) +- 提示词模板：[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) +- packet 模板：[assets/PACKET.template.md](assets/PACKET.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-packet \ + --ref +``` diff --git a/skills/skill-context-packet/SKILL.md b/skills/skill-context-packet/SKILL.md new file mode 100644 index 0000000..21cf6b5 --- /dev/null +++ b/skills/skill-context-packet/SKILL.md @@ -0,0 +1,37 @@ +--- +name: skill-context-packet +description: Use when the next turn needs a minimum context packet rather than a full root or subtask state refresh. +--- + +# Skill Context Packet + +## Overview + +Use this package when the next root or subtask turn needs a compact packet instead of a full state file. +Keep the package boundary narrow: compress the minimum context object for the next turn without taking over root-state refresh, subtask-state refresh, workflow gates, or handoffs. + +## Use This Skill When + +- the next turn only needs a small packet of facts, constraints, and exact next action +- a root or subtask state file is getting too large to inject directly +- you want to hand a bounded task slice to another owner without copying the full history +- you need a packet-first workflow that protects context budget + +## Do Not Use This Skill When + +- the root task or subtask state itself needs a full refresh +- the task needs a risky-change checkpoint or phase gate +- the work is pausing and needs a handoff summary +- the repo needs suite bootstrap or routing guidance + +## Package Boundary + +This package owns packet compression such as `.agent-state/root/PACKET.md` or `.agent-state/subtasks//PACKET.md`. +It does not own root task state, does not own workflow gates, and does not own final handoffs. + +## References + +- `README.md` and `README.zh-CN.md`: entry docs and direct invocation wording +- `references/use-cases.md`: positive and negative trigger examples +- `references/prompt-templates.en.md`: reusable packet-writing prompts +- `assets/PACKET.template.md`: packet template diff --git a/skills/skill-context-packet/agents/openai.yaml b/skills/skill-context-packet/agents/openai.yaml new file mode 100644 index 0000000..d915605 --- /dev/null +++ b/skills/skill-context-packet/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Skill Context Packet" + short_description: "Compress the next turn into a minimum context object" + default_prompt: "Use $skill-context-packet when the next root or subtask turn needs a compact packet instead of a full state file: write .agent-state/root/PACKET.md or .agent-state/subtasks//PACKET.md, preserve only the minimum objective, scope, inputs, facts, constraints, risks, exit criteria, and next command, and avoid taking over root-state refresh, subtask-state refresh, workflow gates, or handoffs." diff --git a/skills/skill-context-packet/assets/PACKET.template.md b/skills/skill-context-packet/assets/PACKET.template.md new file mode 100644 index 0000000..5a309ff --- /dev/null +++ b/skills/skill-context-packet/assets/PACKET.template.md @@ -0,0 +1,32 @@ +# Context Packet + +## Objective For This Turn +- State the exact action this packet should enable. +- Keep it narrow enough for one owner and one short execution loop. + +## Scope For This Turn +- List what this turn should cover. +- List what should stay out of scope for now. + +## Inputs To Load +- Name the smallest set of files, notes, or commands worth opening first. +- Prefer links and paths over pasted detail. + +## Facts To Preserve +- Record only the verified facts needed for this turn. +- Leave stale or optional detail in longer state files. + +## Constraints To Preserve +- List hard requirements, approvals, and safety limits. +- Separate hard constraints from preferences or guesses. + +## Risks / Open Questions +- Capture blockers, fragile spots, or unknowns that matter right now. +- Drop anything that does not affect the next action. + +## Exit Criteria +- Define what must be true before this packet is considered complete. +- Keep the criteria observable. + +## Next Command / Prompt +- End with the first command, file, or prompt the next agent should use. diff --git a/skills/skill-context-packet/references/README.md b/skills/skill-context-packet/references/README.md new file mode 100644 index 0000000..3f7cc0c --- /dev/null +++ b/skills/skill-context-packet/references/README.md @@ -0,0 +1,4 @@ +# skill-context-packet References + +- [use-cases.md](use-cases.md): positive and negative trigger examples +- [prompt-templates.en.md](prompt-templates.en.md): reusable packet-writing prompts diff --git a/skills/skill-context-packet/references/README.zh-CN.md b/skills/skill-context-packet/references/README.zh-CN.md new file mode 100644 index 0000000..2e36a9c --- /dev/null +++ b/skills/skill-context-packet/references/README.zh-CN.md @@ -0,0 +1,4 @@ +# skill-context-packet 参考资料 + +- [use-cases.zh-CN.md](use-cases.zh-CN.md)：适用与不适用触发示例 +- [prompt-templates.zh-CN.md](prompt-templates.zh-CN.md)：编写 packet 时可复用的提示词模板 diff --git a/skills/skill-context-packet/references/prompt-templates.en.md b/skills/skill-context-packet/references/prompt-templates.en.md new file mode 100644 index 0000000..4793d40 --- /dev/null +++ b/skills/skill-context-packet/references/prompt-templates.en.md @@ -0,0 +1,36 @@ +# skill-context-packet Prompt Templates + +Use these templates when you want `skill-context-packet` to compress the next turn into a minimum context object without drifting into full state refresh, gates, or handoffs. + +## Positive Trigger Prompts + +- `Use skill-context-packet to compress the next turn into .agent-state/root/PACKET.md.` +- `Write a compact packet for this subtask and keep only the facts that still matter.` +- `Shrink this state into a packet-first restart object with one exact next command.` + +## Negative Trigger Prompts + +- `Refresh the full root task state before we continue.` +- `Open a child task with its own local state.` +- `Run a risky-change gate before editing.` +- `Write the pause handoff for the next session.` + +## Compress the Next Turn + +```text +Use skill-context-packet to compress the next turn. +Write or refresh .agent-state/root/PACKET.md or .agent-state/subtasks//PACKET.md, +preserve only the objective, narrow scope, smallest useful inputs, +verified facts, hard constraints, risks, exit criteria, and the next command, +and keep the boundary narrow: packet compression only. +``` + +## Rewrite a Bloated State File into a Packet + +```text +This state file is too large for the next turn. +Compress it into a minimum context object for the next owner. +Drop stale detail, keep only what the next turn must know, +and end with the exact next command or prompt. +Do not refresh full state, run a gate, or generate a handoff. +``` diff --git a/skills/skill-context-packet/references/prompt-templates.zh-CN.md b/skills/skill-context-packet/references/prompt-templates.zh-CN.md new file mode 100644 index 0000000..42f6362 --- /dev/null +++ b/skills/skill-context-packet/references/prompt-templates.zh-CN.md @@ -0,0 +1,36 @@ +# skill-context-packet 提示词模板 + +当你希望 `skill-context-packet` 把下一轮压成一个 minimum context object，而不是去处理完整状态刷新、gate 或 handoff 时，可以使用这些模板。 + +## 适用触发示例 + +- `请用 skill-context-packet 把下一轮压缩到 .agent-state/root/PACKET.md。` +- `请为这个子任务写一个紧凑 packet，只保留仍然相关的事实。` +- `把这份状态缩成一个 packet-first 的重启对象，并以一条精确命令结束。` + +## 不适用触发示例 + +- `在继续之前先刷新完整的根任务状态。` +- `为一个子任务打开独立局部状态。` +- `在编辑之前先跑一次高风险改动 gate。` +- `为下一次会话写暂停 handoff。` + +## 压缩下一轮 + +```text +请用 skill-context-packet 压缩下一轮。 +写入或刷新 .agent-state/root/PACKET.md 或 .agent-state/subtasks//PACKET.md， +只保留目标、收敛后的范围、最小有用输入、 +已验证事实、硬约束、风险、退出条件和下一条命令， +并保持边界收敛：只处理 packet compression。 +``` + +## 把膨胀的状态文件重写成 Packet + +```text +这份状态文件对下一轮来说太大了。 +请把它压缩成面向下一位 owner 的 minimum context object。 +删除陈旧细节，只保留下一轮必须知道的内容， +并以精确的下一条命令或 prompt 结束。 +不要顺手刷新完整状态，不要跑 gate，也不要生成 handoff。 +``` diff --git a/skills/skill-context-packet/references/use-cases.md b/skills/skill-context-packet/references/use-cases.md new file mode 100644 index 0000000..f17b247 --- /dev/null +++ b/skills/skill-context-packet/references/use-cases.md @@ -0,0 +1,38 @@ +# skill-context-packet Use Cases + +`skill-context-packet` is for compressing the next root or subtask turn into a minimum context object. +Use it when the next agent should load only the smallest useful packet instead of a full state file. + +## Positive Trigger Prompts + +- `Use skill-context-packet to compress the next turn into .agent-state/root/PACKET.md.` +- `Write a compact packet for the parser-cleanup subtask and keep only the facts that still matter.` +- `The state file is too large for the next turn. Compress it into a packet-first restart object.` +- `Prepare the minimum context object for a handoff between active owners without rewriting the whole task.` +- `Update the packet so the next agent can start with the exact next command.` + +## Negative Trigger Prompts + +- `Refresh the full root task state before we continue.` +- `Open a new child task with local state and merge notes.` +- `Run a preflight gate before this risky multi-file change.` +- `Write the pause handoff for the next session.` +- `Bootstrap the continuity suite in this repository.` + +## Packet Wording Patterns + +Use wording like this when the request is specifically about packet compression: + +- `Compress the next turn into a packet.` +- `Write the minimum context object for the next agent.` +- `Keep only the facts, constraints, and next command that still matter.` +- `Shrink this state into a packet-first restart note.` + +## Typical Output Shape + +The package usually refreshes `.agent-state/root/PACKET.md` or `.agent-state/subtasks//PACKET.md` with: + +- the objective for the next turn +- the smallest useful scope and input list +- the facts and constraints worth preserving +- risks, exit criteria, and the next command diff --git a/skills/skill-context-packet/references/use-cases.zh-CN.md b/skills/skill-context-packet/references/use-cases.zh-CN.md new file mode 100644 index 0000000..8377d07 --- /dev/null +++ b/skills/skill-context-packet/references/use-cases.zh-CN.md @@ -0,0 +1,38 @@ +# skill-context-packet 用例 + +`skill-context-packet` 用于把下一轮 root 或 subtask 压缩成一个 minimum context object。 +当下一位 agent 只该加载最小有用 packet，而不是整份状态文件时，就应该触发它。 + +## 适用触发示例 + +- `请用 skill-context-packet 把下一轮压缩到 .agent-state/root/PACKET.md。` +- `请为 parser-cleanup 这个子任务写一个紧凑 packet，只保留仍然相关的事实。` +- `状态文件对下一轮来说太大了，请把它压成 packet-first 的重启对象。` +- `在活跃 owner 之间交接时，只准备 minimum context object，不要重写整个任务。` +- `请更新 packet，让下一位 agent 能从精确的下一条命令开始。` + +## 不适用触发示例 + +- `在继续之前先刷新完整的根任务状态。` +- `为一个新子任务建立局部状态和 merge notes。` +- `在这个高风险多文件改动前先跑 preflight gate。` +- `给下一次会话写暂停 handoff。` +- `在这个仓库里启动整套连续性工具链。` + +## Packet 措辞模式 + +当需求明确是“packet 压缩”时，可以使用这类措辞： + +- `把下一轮压成一个 packet。` +- `为下一位 agent 写 minimum context object。` +- `只保留仍然重要的事实、约束和下一条命令。` +- `把这份状态缩成一个 packet-first 的重启说明。` + +## 典型输出形态 + +这个包通常会刷新 `.agent-state/root/PACKET.md` 或 `.agent-state/subtasks//PACKET.md`，其中包括： + +- 下一轮目标 +- 最小有用范围和输入列表 +- 值得保留的事实与约束 +- 风险、退出条件和下一条命令 diff --git a/skills/skill-context-packet/tests/test_package_contract.py b/skills/skill-context-packet/tests/test_package_contract.py new file mode 100644 index 0000000..8361008 --- /dev/null +++ b/skills/skill-context-packet/tests/test_package_contract.py @@ -0,0 +1,107 @@ +from pathlib import Path +import unittest + + +ROOT = Path(__file__).resolve().parents[1] + + +class SkillContextPacketPackageTests(unittest.TestCase): + def test_skill_frontmatter_name(self): + text = (ROOT / "SKILL.md").read_text(encoding="utf-8") + self.assertIn("name: skill-context-packet", text) + + def test_core_package_files_exist(self): + for path in [ + ROOT / "README.md", + ROOT / "README.zh-CN.md", + ROOT / "SKILL.md", + ROOT / "agents" / "openai.yaml", + ROOT / "references" / "README.md", + ROOT / "references" / "README.zh-CN.md", + ROOT / "references" / "use-cases.md", + ROOT / "references" / "use-cases.zh-CN.md", + ROOT / "references" / "prompt-templates.en.md", + ROOT / "references" / "prompt-templates.zh-CN.md", + ROOT / "assets" / "PACKET.template.md", + ]: + self.assertTrue(path.exists(), f"expected package file to exist: {path}") + + def test_packet_template_has_required_sections(self): + text = (ROOT / "assets" / "PACKET.template.md").read_text(encoding="utf-8") + for heading in [ + "# Context Packet", + "## Objective For This Turn", + "## Scope For This Turn", + "## Inputs To Load", + "## Facts To Preserve", + "## Constraints To Preserve", + "## Risks / Open Questions", + "## Exit Criteria", + "## Next Command / Prompt", + ]: + self.assertIn(heading, text) + + def test_bilingual_use_cases_include_trigger_sections(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") + + self.assertRegex(english, r"(?im)^## +Positive Trigger Prompts$") + self.assertRegex(english, r"(?im)^## +Negative Trigger Prompts$") + self.assertRegex(chinese, r"(?m)^## +适用触发示例$") + self.assertRegex(chinese, r"(?m)^## +不适用触发示例$") + + def test_readme_describes_packet_boundary(self): + text = (ROOT / "README.md").read_text(encoding="utf-8").lower() + self.assertIn("minimum context object", text) + self.assertIn("does not own root task state", text) + self.assertIn("does not own workflow gates", 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-packet to compress the next turn", + text, + ) + + def test_readme_has_fast_entry_sections(self): + text = (ROOT / "README.md").read_text(encoding="utf-8") + for heading in [ + "## Start Here In 30 Seconds", + "## Install", + "## What File Will This Create Or Update?", + "## Don't Use This When", + "## Related Skills", + ]: + self.assertIn(heading, text) + self.assertIn("Typical output:", text) + self.assertIn(".agent-state/root/PACKET.md", text) + self.assertIn("Try this first:", text) + self.assertIn("Use skill-context-packet", text) + + def test_chinese_readme_has_fast_entry_sections(self): + text = (ROOT / "README.zh-CN.md").read_text(encoding="utf-8") + for heading in [ + "## 30 秒快速开始", + "## 安装", + "## 会创建或更新什么文件？", + "## 不适合什么时候用", + "## 相关技能", + ]: + self.assertIn(heading, text) + self.assertIn("典型产物：", text) + self.assertIn(".agent-state/root/PACKET.md", text) + self.assertIn("先这样对 Codex 说：", text) + self.assertIn("请用 skill-context-packet", 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") + + for text in [english, chinese]: + self.assertIn("use-cases", text) + self.assertIn("prompt-templates", text) + + +if __name__ == "__main__": + unittest.main() diff --git a/skills/skill-governance/README.md b/skills/skill-governance/README.md index fd3af2e..e19534e 100644 --- a/skills/skill-governance/README.md +++ b/skills/skill-governance/README.md @@ -37,7 +37,7 @@ To install `skill-governance`, use the standard package path in your Codex works You can ask Codex in natural language: - `Use skill-installer to install skill-governance from Golden-Promise/codex-skill-library at skills/skill-governance.` -- `Use skill-installer to install skill-governance from Golden-Promise/codex-skill-library at skills/skill-governance using ref v0.6.1.` +- `Use skill-installer to install skill-governance from Golden-Promise/codex-skill-library at skills/skill-governance using ref .` For command patterns and advanced installation notes, see [references/use-cases.md](references/use-cases.md). diff --git a/skills/skill-governance/README.zh-CN.md b/skills/skill-governance/README.zh-CN.md index 12d2127..1d7e8b3 100644 --- a/skills/skill-governance/README.zh-CN.md +++ b/skills/skill-governance/README.zh-CN.md @@ -37,7 +37,7 @@ 你也可以直接这样对 Codex 说： - `请用 skill-installer 从 Golden-Promise/codex-skill-library 的 skills/skill-governance 安装 skill-governance。` -- `请用 skill-installer 从 Golden-Promise/codex-skill-library 的 skills/skill-governance 安装 skill-governance，并使用 ref v0.6.1。` +- `请用 skill-installer 从 Golden-Promise/codex-skill-library 的 skills/skill-governance 安装 skill-governance，并使用 ref 。` 关于命令模式和进阶说明，请查看 [references/use-cases.zh-CN.md](references/use-cases.zh-CN.md)。 diff --git a/skills/skill-governance/docs/publishing-with-skill-installer.md b/skills/skill-governance/docs/publishing-with-skill-installer.md index d744440..444e9f7 100644 --- a/skills/skill-governance/docs/publishing-with-skill-installer.md +++ b/skills/skill-governance/docs/publishing-with-skill-installer.md @@ -47,13 +47,13 @@ python3 /scripts/install-skill-from-github.py \ --path skills/skill-governance ``` -If you want to pin the current release, use: +If you want to pin a specific release, use: ```bash python3 /scripts/install-skill-from-github.py \ --repo Golden-Promise/codex-skill-library \ --path skills/skill-governance \ - --ref v0.6.1 + --ref ``` ## Repository Files In This Repo diff --git a/skills/skill-governance/docs/publishing-with-skill-installer.zh-CN.md b/skills/skill-governance/docs/publishing-with-skill-installer.zh-CN.md index 1e2cbca..6dc392a 100644 --- a/skills/skill-governance/docs/publishing-with-skill-installer.zh-CN.md +++ b/skills/skill-governance/docs/publishing-with-skill-installer.zh-CN.md @@ -47,13 +47,13 @@ python3 /scripts/install-skill-from-github.py \ --path skills/skill-governance ``` -如果要固定安装当前发布版本，可使用： +如果要固定安装某个发布版本，可使用： ```bash python3 /scripts/install-skill-from-github.py \ --repo Golden-Promise/codex-skill-library \ --path skills/skill-governance \ - --ref v0.6.1 + --ref ``` ## 当前仓库中的根文件 diff --git a/skills/skill-governance/references/use-cases.md b/skills/skill-governance/references/use-cases.md index f182e10..075499d 100644 --- a/skills/skill-governance/references/use-cases.md +++ b/skills/skill-governance/references/use-cases.md @@ -22,7 +22,7 @@ Install a specific tagged release: python3 /scripts/install-skill-from-github.py \ --repo Golden-Promise/codex-skill-library \ --path skills/skill-governance \ - --ref v0.6.1 + --ref ``` ## Commands diff --git a/skills/skill-governance/references/use-cases.zh-CN.md b/skills/skill-governance/references/use-cases.zh-CN.md index bd165c8..65800e2 100644 --- a/skills/skill-governance/references/use-cases.zh-CN.md +++ b/skills/skill-governance/references/use-cases.zh-CN.md @@ -22,7 +22,7 @@ python3 /scripts/install-skill-from-github.py \ python3 /scripts/install-skill-from-github.py \ --repo Golden-Promise/codex-skill-library \ --path skills/skill-governance \ - --ref v0.6.1 + --ref ``` ## 命令总览 diff --git a/skills/skill-handoff-summary/README.md b/skills/skill-handoff-summary/README.md index 91fa612..0468113 100644 --- a/skills/skill-handoff-summary/README.md +++ b/skills/skill-handoff-summary/README.md @@ -5,13 +5,13 @@ ## Overview `skill-handoff-summary` is the focused package for writing continuation-oriented pause or transfer notes. -It is for compact downstream artifacts such as `.agent-state/HANDOFF.md`, not whole-project documentation. +It is for compact downstream artifacts such as `.agent-state/root/HANDOFF.md` or `.agent-state/subtasks//HANDOFF.md`, not whole-project documentation. ## Start Here In 30 Seconds - Use this when: work is about to pause, switch owners, or cross into a new session. - You'll get: a compact restart note with current status, hard constraints, open problems, and the exact next action. -- Typical output: updates `.agent-state/HANDOFF.md`. +- Typical output: updates `.agent-state/root/HANDOFF.md` or `.agent-state/subtasks//HANDOFF.md`. Need a durable restart note? Use this. Just need a quick status update in chat? Don't use this. @@ -20,22 +20,22 @@ If you want to tell Codex exactly what to do: Try this first: -- `Use skill-handoff-summary to write a compact continuation-oriented handoff before we pause.` +- `Use skill-handoff-summary to write a compact continuation-oriented handoff for the root task or a subtask before we pause.` ## Install You can ask Codex in natural language: - `Use skill-installer to install skill-handoff-summary from Golden-Promise/codex-skill-library at skills/skill-handoff-summary.` -- `Use skill-installer to install skill-handoff-summary from Golden-Promise/codex-skill-library at skills/skill-handoff-summary using ref v0.6.1.` +- `Use skill-installer to install skill-handoff-summary from Golden-Promise/codex-skill-library at skills/skill-handoff-summary using ref .` If you want the exact shell command, jump to [Install Details](#install-details). ## What File Will This Create Or Update? -The typical downstream file is `.agent-state/HANDOFF.md`. +The typical downstream files are `.agent-state/root/HANDOFF.md` and `.agent-state/subtasks//HANDOFF.md`. -Use this package when you want that file to preserve: +Use this package when you want one of those files to preserve: - task summary - current status @@ -48,13 +48,18 @@ Use this package when you want that file to preserve: ## Don't Use This When - you need to rebuild the current task state before more work continues +- you need a root-state refresh instead of a pause artifact - you need a checkpoint around a risky or multi-file change - you only need a quick status note inside the current chat - you want whole-project documentation instead of a continuation-oriented handoff +This package is continuation-oriented, does not own root-state refresh, and does not own workflow gates. + ## Related Skills -- `skill-context-keeper` for refreshing `.agent-state/TASK_STATE.md` +- `skill-context-keeper` for refreshing `.agent-state/root/TASK_STATE.md` +- `skill-subtask-context` for `.agent-state/subtasks//TASK_STATE.md` +- `skill-context-packet` for packet-sized next-turn context - `skill-phase-gate` for preflight and postflight checkpoints - `skill-task-continuity` for first-time continuity setup and routing @@ -76,5 +81,5 @@ Replace `/path/to/install-skill-from-github.py` with the actual path to your loc python3 /path/to/install-skill-from-github.py \ --repo Golden-Promise/codex-skill-library \ --path skills/skill-handoff-summary \ - --ref v0.6.1 + --ref ``` diff --git a/skills/skill-handoff-summary/README.zh-CN.md b/skills/skill-handoff-summary/README.zh-CN.md index c1bebcf..3ff69e0 100644 --- a/skills/skill-handoff-summary/README.zh-CN.md +++ b/skills/skill-handoff-summary/README.zh-CN.md @@ -5,13 +5,13 @@ ## 概述 `skill-handoff-summary` 是一个专注型包，用于写出面向续做的暂停说明或转交说明。 -它服务的是诸如 `.agent-state/HANDOFF.md` 这样的紧凑下游产物，而不是整项目文档。 +它服务的是诸如 `.agent-state/root/HANDOFF.md` 或 `.agent-state/subtasks//HANDOFF.md` 这样的紧凑下游产物，而不是整项目文档。 ## 30 秒快速开始 - 什么时候用：工作马上要暂停、换人，或者切进新的会话。 - 你会得到什么：一份紧凑的重启说明，里面有当前状态、硬约束、开放问题和精确下一步。 -- 典型产物：更新 `.agent-state/HANDOFF.md`。 +- 典型产物：更新 `.agent-state/root/HANDOFF.md` 或 `.agent-state/subtasks//HANDOFF.md`。 如果你需要一份耐用的重启说明，就用它。 如果你只是想在聊天里快速同步状态，就不要用它。 @@ -20,22 +20,22 @@ 先这样对 Codex 说： -- `请用 skill-handoff-summary 在暂停前写一个紧凑、面向续做的交接摘要。` +- `请用 skill-handoff-summary 在暂停前为根任务或某个子任务写一个紧凑、面向续做的交接摘要。` ## 安装 你可以直接这样对 Codex 说： - `请用 skill-installer 从 Golden-Promise/codex-skill-library 的 skills/skill-handoff-summary 安装 skill-handoff-summary。` -- `请用 skill-installer 从 Golden-Promise/codex-skill-library 的 skills/skill-handoff-summary 安装 skill-handoff-summary，并使用 ref v0.6.1。` +- `请用 skill-installer 从 Golden-Promise/codex-skill-library 的 skills/skill-handoff-summary 安装 skill-handoff-summary，并使用 ref 。` 如果你想看精确的 shell 命令，可以直接跳到后面的 [安装细节](#安装细节)。 ## 会创建或更新什么文件？ -最典型的下游文件是 `.agent-state/HANDOFF.md`。 +最典型的下游文件是 `.agent-state/root/HANDOFF.md` 和 `.agent-state/subtasks//HANDOFF.md`。 -当你希望这个文件帮你保留下列信息时，就该用这个包： +当你希望这些文件帮你保留下列信息时，就该用这个包： - 任务摘要 - 当前状态 @@ -48,13 +48,18 @@ ## 不适合什么时候用 - 你需要在继续工作前先重建当前任务状态 +- 你真正需要的是 root-state refresh，而不是暂停产物 - 你需要给高风险或多文件改动加检查点 - 你只是想在当前聊天里快速同步一下状态 - 你要写的是整项目说明，而不是 continuation-oriented handoff +这个包是 continuation-oriented，不负责 root-state refresh，也不负责 workflow gates。 + ## 相关技能 -- `skill-context-keeper`：适合刷新 `.agent-state/TASK_STATE.md` +- `skill-context-keeper`：适合刷新 `.agent-state/root/TASK_STATE.md` +- `skill-subtask-context`：适合处理 `.agent-state/subtasks//TASK_STATE.md` +- `skill-context-packet`：适合处理 packet-sized 的下一轮上下文 - `skill-phase-gate`：适合 preflight / postflight 检查点 - `skill-task-continuity`：适合第一次搭建流程和做套件级路由 @@ -76,5 +81,5 @@ python3 /path/to/install-skill-from-github.py \ --repo Golden-Promise/codex-skill-library \ --path skills/skill-handoff-summary \ - --ref v0.6.1 + --ref ``` diff --git a/skills/skill-handoff-summary/SKILL.md b/skills/skill-handoff-summary/SKILL.md index 430db18..f62d3e1 100644 --- a/skills/skill-handoff-summary/SKILL.md +++ b/skills/skill-handoff-summary/SKILL.md @@ -1,6 +1,6 @@ --- name: skill-handoff-summary -description: Use when an ongoing coding task needs a compact continuation-oriented handoff summary, especially before pausing or transferring ownership, without turning it into full-project documentation or workflow control. +description: Use when an ongoing coding task needs a compact root-task or subtask handoff before pausing or transferring ownership, without turning it into full-project documentation, root-state refresh, or workflow control. --- # Skill Handoff Summary @@ -9,18 +9,26 @@ description: Use when an ongoing coding task needs a compact continuation-orient Capture a concise continuation-oriented handoff for a coding task that will resume later in the same thread or a new one. This package specializes in compact handoff creation only. -It can target downstream artifacts such as `.agent-state/HANDOFF.md`, but it does not own long-term state and it does not own workflow gating. +It can target downstream artifacts such as `.agent-state/root/HANDOFF.md` or `.agent-state/subtasks//HANDOFF.md`, but it does not own root-state refresh and it does not own workflow gating. ## Use This Skill When - pausing work and needing a clean continuation note for later resumption - transferring a task to another agent with open questions, constraints, and an exact next action -- writing or refreshing a compact artifact such as `.agent-state/HANDOFF.md` +- writing or refreshing a compact artifact such as `.agent-state/root/HANDOFF.md` +- writing or refreshing a compact artifact such as `.agent-state/subtasks//HANDOFF.md` - reducing restart cost after a stop point in a long thread +## Do Not Use This Skill When + +- the main need is rebuilding root-task state before more work continues +- the main need is creating subtask-local state instead of a pause artifact +- the main need is packet compression for the next live turn +- the request is asking for a workflow gate rather than a continuation handoff + ## References - `README.md` and `README.zh-CN.md`: package overview, boundary guidance, and install notes - `references/use-cases.md` and `references/use-cases.zh-CN.md`: positive and negative trigger examples - `references/prompt-templates.en.md` and `references/prompt-templates.zh-CN.md`: reusable pause and resume wording -- `assets/HANDOFF.template.md`: compact template for `.agent-state/HANDOFF.md` +- `assets/HANDOFF.template.md`: compact template for root or subtask handoffs diff --git a/skills/skill-handoff-summary/agents/openai.yaml b/skills/skill-handoff-summary/agents/openai.yaml index 45a6b0d..74a9a43 100644 --- a/skills/skill-handoff-summary/agents/openai.yaml +++ b/skills/skill-handoff-summary/agents/openai.yaml @@ -1,4 +1,4 @@ interface: display_name: "Skill Handoff Summary" short_description: "Write compact continuation handoffs for paused or transferred coding work" - default_prompt: "Use $skill-handoff-summary when a coding task is pausing or changing hands: write a compact continuation-oriented handoff, optionally to .agent-state/HANDOFF.md, with current status, session changes, preserved constraints, open problems, the exact next action, and a reusable resume prompt. Do not turn it into whole-project documentation, long-term state management, or workflow gating." + default_prompt: "Use $skill-handoff-summary when a coding task is pausing or changing hands: write a compact continuation-oriented handoff for the root task or a subtask, optionally to .agent-state/root/HANDOFF.md or .agent-state/subtasks//HANDOFF.md, with current status, session changes, preserved constraints, open problems, the exact next action, and a reusable resume prompt. Do not turn it into whole-project documentation, root-state refresh, long-term state management, or workflow gating." diff --git a/skills/skill-handoff-summary/assets/HANDOFF.template.md b/skills/skill-handoff-summary/assets/HANDOFF.template.md index 062bcf5..2a00410 100644 --- a/skills/skill-handoff-summary/assets/HANDOFF.template.md +++ b/skills/skill-handoff-summary/assets/HANDOFF.template.md @@ -22,4 +22,4 @@ List blockers, unresolved questions, or risks that still need work. Write the single next action that should happen first when work resumes. ## Resume Prompt -Resume this task from .agent-state/HANDOFF.md. Continue from the recorded status, preserve the listed constraints, inspect the files of interest, resolve the open problems in priority order, perform the exact next action first, and update the handoff if anything material changes. +Resume this task from the recorded handoff. Continue from the recorded status, preserve the listed constraints, inspect the files of interest, resolve the open problems in priority order, perform the exact next action first, and update the handoff if anything material changes. diff --git a/skills/skill-handoff-summary/references/prompt-templates.en.md b/skills/skill-handoff-summary/references/prompt-templates.en.md index 59971e6..8cbf2e8 100644 --- a/skills/skill-handoff-summary/references/prompt-templates.en.md +++ b/skills/skill-handoff-summary/references/prompt-templates.en.md @@ -1,11 +1,12 @@ # skill-handoff-summary Prompt Templates -Use these templates when you want `skill-handoff-summary` to create a compact continuation handoff without drifting into whole-project documentation, long-term state management, or workflow gating. +Use these templates when you want `skill-handoff-summary` to create a compact continuation handoff without drifting into whole-project documentation, root-state refresh, long-term state management, or workflow gating. ## Positive Trigger Prompts - `Use skill-handoff-summary to capture a continuation handoff before we pause this task.` -- `Write .agent-state/HANDOFF.md with current status, preserved constraints, open problems, and the exact next action.` +- `Write .agent-state/root/HANDOFF.md with current status, preserved constraints, open problems, and the exact next action.` +- `Write .agent-state/subtasks//HANDOFF.md with current status, preserved constraints, open problems, and the exact next action.` - `Prepare a concise transfer note for the next agent and end with a reusable resume prompt.` ## Negative Trigger Prompts @@ -13,22 +14,23 @@ Use these templates when you want `skill-handoff-summary` to create a compact co - `Give me a short status update in chat and do not write any durable artifact.` - `Document the whole repository for future maintainers.` - `Rebuild the current task state and decide the next workflow gate.` +- `Refresh the root task state instead of writing a pause artifact.` ## Write A Compact Handoff ```text -Use skill-handoff-summary to write a compact continuation-oriented handoff. -Target .agent-state/HANDOFF.md. +Use skill-handoff-summary to write a compact continuation-oriented handoff for the root task or a subtask. +Target .agent-state/root/HANDOFF.md or .agent-state/subtasks//HANDOFF.md. Summarize the task, current status, changes from this session, hard constraints to preserve, files or modules of interest, open problems, and the exact next action. End with a resume prompt the next session can reuse immediately. -Do not turn it into whole-project documentation, long-term state, or workflow gating. +Do not turn it into whole-project documentation, root-state refresh, long-term state, or workflow gating. ``` ## Resume Prompt ```text -Resume this task from .agent-state/HANDOFF.md. +Resume this task from the recorded handoff. Continue from the recorded status, preserve the listed constraints, inspect the files of interest, resolve the open problems in priority order, perform the exact next action first, and update the handoff if anything material changes. diff --git a/skills/skill-handoff-summary/references/prompt-templates.zh-CN.md b/skills/skill-handoff-summary/references/prompt-templates.zh-CN.md index c58ab26..508c692 100644 --- a/skills/skill-handoff-summary/references/prompt-templates.zh-CN.md +++ b/skills/skill-handoff-summary/references/prompt-templates.zh-CN.md @@ -1,11 +1,12 @@ # skill-handoff-summary 提示词模板 -当你希望 `skill-handoff-summary` 生成一份紧凑、面向续做的交接摘要，而且不要偏离到整项目文档、长期状态管理或工作流门控时，可以直接复用下面这些模板。 +当你希望 `skill-handoff-summary` 生成一份紧凑、面向续做的交接摘要，而且不要偏离到整项目文档、root-state refresh、长期状态管理或工作流门控时，可以直接复用下面这些模板。 ## 适用触发示例 - `请使用 skill-handoff-summary 在暂停这个任务前生成一份续做交接。` -- `请把当前状态、需保留的约束、开放问题和精确下一步写入 .agent-state/HANDOFF.md。` +- `请把当前状态、需保留的约束、开放问题和精确下一步写入 .agent-state/root/HANDOFF.md。` +- `请把当前状态、需保留的约束、开放问题和精确下一步写入 .agent-state/subtasks//HANDOFF.md。` - `请为下一位代理准备一份简洁的转交说明，并在结尾附上可复用的 resume prompt。` ## 不适用触发示例 @@ -13,22 +14,23 @@ - `直接在聊天里给我一个简短状态更新，不要写任何持久文件。` - `为未来维护者把整个仓库写成完整文档。` - `重建当前任务状态，并决定下一个工作流 gate。` +- `请先刷新 root 任务状态，而不是写暂停交接。` ## 生成紧凑交接 ```text -请使用 skill-handoff-summary 生成一份紧凑、面向续做的交接摘要。 -目标路径是 .agent-state/HANDOFF.md。 +请使用 skill-handoff-summary 为根任务或某个子任务生成一份紧凑、面向续做的交接摘要。 +目标路径是 .agent-state/root/HANDOFF.md 或 .agent-state/subtasks//HANDOFF.md。 总结任务、当前状态、本次会话中的变更、需要保留的硬约束、 相关文件或模块、开放问题，以及精确的下一步动作。 最后附上一段下一次会话可直接复用的 resume prompt。 -不要把它扩展成整项目文档、长期状态或工作流门控。 +不要把它扩展成整项目文档、root-state refresh、长期状态或工作流门控。 ``` ## Resume Prompt ```text -请从 .agent-state/HANDOFF.md 继续这个任务。 +请从记录好的 handoff 继续这个任务。 沿着已记录的当前状态往下推进，保留其中列出的约束，先检查提到的相关文件， 再按优先级处理开放问题，优先执行“精确下一步动作”， 并在出现任何重要变化时更新这份交接。 diff --git a/skills/skill-handoff-summary/references/use-cases.md b/skills/skill-handoff-summary/references/use-cases.md index 48c2f02..54b10e8 100644 --- a/skills/skill-handoff-summary/references/use-cases.md +++ b/skills/skill-handoff-summary/references/use-cases.md @@ -1,12 +1,13 @@ # skill-handoff-summary Use Cases `skill-handoff-summary` is for compact continuation-oriented handoffs when coding work is about to pause or move to another owner. -Use it when the next session needs a trusted restart note, not when the conversation only needs a casual status update or a whole-project writeup. +Use it when the next session needs a trusted restart note for a root task or a subtask, not when the conversation only needs a casual status update, root-state refresh, or a whole-project writeup. ## Positive Trigger Prompts - `Use skill-handoff-summary to write a compact handoff before we pause for today.` -- `Write .agent-state/HANDOFF.md so the next session can resume this task without rereading the whole thread.` +- `Write .agent-state/root/HANDOFF.md so the next session can resume this task without rereading the whole thread.` +- `Write .agent-state/subtasks/parser-cleanup/HANDOFF.md so the next session can resume the child task without rereading the whole thread.` - `Capture the current status, hard constraints, open problems, and exact next action for the next agent taking over.` - `We are handing this thread to another coder. Prepare a concise continuation handoff with a resume prompt.` - `Before stopping, turn this session into a short transfer summary instead of a full project recap.` @@ -16,6 +17,7 @@ Use it when the next session needs a trusted restart note, not when the conversa - `Give me a quick status update in chat about what changed today.` - `Write full project documentation for the repository so a new team can onboard.` - `Refresh the current task state from the repo before we continue coding right now.` +- `Refresh the root task state before we continue coding right now.` - `Decide the next phase gate and tell me whether implementation can start.` - `Create one big summary that covers planning, long-term state, and final handoff together.` @@ -33,4 +35,4 @@ Do not use it to produce full-project documentation, rebuild long-term task stat Use wording like this when you want the next session to restart immediately: -`Resume this task from .agent-state/HANDOFF.md. Continue from the recorded status, preserve the listed constraints, inspect the files of interest, resolve the open problems in priority order, perform the exact next action first, and update the handoff if anything material changes.` +`Resume this task from the recorded handoff. Continue from the recorded status, preserve the listed constraints, inspect the files of interest, resolve the open problems in priority order, perform the exact next action first, and update the handoff if anything material changes.` diff --git a/skills/skill-handoff-summary/references/use-cases.zh-CN.md b/skills/skill-handoff-summary/references/use-cases.zh-CN.md index 0a2ddd5..13ed052 100644 --- a/skills/skill-handoff-summary/references/use-cases.zh-CN.md +++ b/skills/skill-handoff-summary/references/use-cases.zh-CN.md @@ -1,12 +1,13 @@ # skill-handoff-summary 使用场景 `skill-handoff-summary` 适用于在编码工作即将暂停，或即将转交给另一位执行者时，生成紧凑、面向续做的交接摘要。 -当下一次会话需要一个可信的重启说明时使用它；如果只是随手在聊天里汇报进度，或者要写成整项目文档，就不该由这个包接管。 +当下一次会话需要一个可信的根任务或子任务重启说明时使用它；如果只是随手在聊天里汇报进度、刷新 root 状态，或者要写成整项目文档，就不该由这个包接管。 ## 适用触发示例 - `请使用 skill-handoff-summary 在今天暂停前写一份紧凑交接。` -- `请生成 .agent-state/HANDOFF.md，让下一次会话不用重读整个线程也能继续。` +- `请生成 .agent-state/root/HANDOFF.md，让下一次会话不用重读整个线程也能继续。` +- `请生成 .agent-state/subtasks/parser-cleanup/HANDOFF.md，让下一次会话不用重读整个线程也能继续子任务。` - `把当前状态、必须保留的硬约束、开放问题和精确下一步整理给下一位接手的人。` - `这个线程要转给另一位开发者了，请准备一份附带 resume prompt 的简洁续做交接。` - `在停下来之前，把这次会话整理成短交接说明，而不是完整项目回顾。` @@ -16,6 +17,7 @@ - `直接在聊天里给我一句今天做了什么的状态更新。` - `请为整个仓库写一套完整项目文档，方便新团队成员上手。` - `继续编码前，先根据仓库刷新当前任务状态。` +- `继续编码前，先把 root 任务状态刷新到最新。` - `决定下一阶段的 gate，并告诉我现在能不能开始实现。` - `把规划、长期状态和最终交接合成一份大总结。` @@ -33,4 +35,4 @@ 当你希望下一次会话拿来就继续做时，可以直接使用这句： -`请从 .agent-state/HANDOFF.md 继续这个任务。沿着已记录的当前状态往下推进，保留其中列出的约束，先检查提到的相关文件，再按优先级处理开放问题，优先执行“精确下一步动作”，并在出现任何重要变化时更新这份交接。` +`请从记录好的 handoff 继续这个任务。沿着已记录的当前状态往下推进，保留其中列出的约束，先检查提到的相关文件，再按优先级处理开放问题，优先执行“精确下一步动作”，并在出现任何重要变化时更新这份交接。` diff --git a/skills/skill-handoff-summary/tests/test_package_contract.py b/skills/skill-handoff-summary/tests/test_package_contract.py index 5a5ad22..61307f3 100644 --- a/skills/skill-handoff-summary/tests/test_package_contract.py +++ b/skills/skill-handoff-summary/tests/test_package_contract.py @@ -41,13 +41,15 @@ def test_readme_describes_continuation_boundary(self): text = (ROOT / "README.md").read_text(encoding="utf-8").lower() self.assertIn("continuation-oriented", text) self.assertIn("not whole-project documentation", text) - self.assertIn(".agent-state/handoff.md", text) + self.assertIn(".agent-state/root/handoff.md", text) + self.assertIn(".agent-state/subtasks//handoff.md", text) + self.assertIn("does not own root-state refresh", 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", + "use skill-handoff-summary to write a compact continuation-oriented handoff for the root task or a subtask", text, ) @@ -63,7 +65,8 @@ def test_bilingual_references_include_positive_and_negative_examples(self): def test_resume_prompt_is_explicitly_present_in_template(self): text = (ROOT / "assets" / "HANDOFF.template.md").read_text(encoding="utf-8") self.assertIn("Resume Prompt", text) - self.assertIn("Resume this task from .agent-state/HANDOFF.md.", text) + self.assertIn("Resume this task from the recorded handoff.", text) + self.assertNotIn(".agent-state/HANDOFF.md", text) def test_chinese_references_use_natural_resume_prompt_wording(self): for path in [ @@ -71,7 +74,7 @@ def test_chinese_references_use_natural_resume_prompt_wording(self): ROOT / "references" / "prompt-templates.zh-CN.md", ]: text = path.read_text(encoding="utf-8") - self.assertIn("请从 .agent-state/HANDOFF.md 继续这个任务。", text) + self.assertIn("请从记录好的 handoff 继续这个任务。", text) def test_readme_has_fast_entry_sections(self): text = (ROOT / "README.md").read_text(encoding="utf-8") @@ -84,7 +87,8 @@ def test_readme_has_fast_entry_sections(self): ]: self.assertIn(heading, text) self.assertIn("Typical output:", text) - self.assertIn(".agent-state/HANDOFF.md", text) + self.assertIn(".agent-state/root/HANDOFF.md", text) + self.assertIn(".agent-state/subtasks//HANDOFF.md", text) self.assertIn("Try this first:", text) self.assertIn("Use skill-handoff-summary", text) self.assertIn("Just need a quick status update in chat?", text) @@ -100,7 +104,8 @@ def test_chinese_readme_has_fast_entry_sections(self): ]: self.assertIn(heading, text) self.assertIn("典型产物：", text) - self.assertIn(".agent-state/HANDOFF.md", text) + self.assertIn(".agent-state/root/HANDOFF.md", text) + self.assertIn(".agent-state/subtasks//HANDOFF.md", text) self.assertIn("先这样对 Codex 说：", text) self.assertIn("请用 skill-handoff-summary", text) self.assertIn("如果你只是想在聊天里快速同步状态", text) diff --git a/skills/skill-phase-gate/README.md b/skills/skill-phase-gate/README.md index 358ec02..2ec2b03 100644 --- a/skills/skill-phase-gate/README.md +++ b/skills/skill-phase-gate/README.md @@ -4,8 +4,8 @@ ## Overview -`skill-phase-gate` adds compact preflight and postflight checkpoints around meaningful coding work. -If the checkpoint itself adds value, use this skill. +`skill-phase-gate` adds an optional operational checkpoint around meaningful coding work. +If the checkpoint itself adds value for risky edits, use this skill. ## Start Here In 30 Seconds @@ -24,7 +24,7 @@ Try this first: You can ask Codex in natural language: - `Use skill-installer to install skill-phase-gate from Golden-Promise/codex-skill-library at skills/skill-phase-gate.` -- `Use skill-installer to install skill-phase-gate from Golden-Promise/codex-skill-library at skills/skill-phase-gate using ref v0.6.1.` +- `Use skill-installer to install skill-phase-gate from Golden-Promise/codex-skill-library at skills/skill-phase-gate using ref .` If you want the exact shell command, jump to [Install Details](#install-details). @@ -42,13 +42,19 @@ Use the shipped templates as the starting shape: - the change is a trivial one-line edit - the work is a pure explanation task - the main problem is stale task state rather than checkpoint value +- the main problem is root-state refresh rather than checkpoint value +- the main problem is packet compression rather than checkpoint value +- the main problem is suite bootstrap rather than checkpoint value - you need a pause or transfer handoff instead of a workflow checkpoint -This package is not for trivial one-line edits and is not for pure explanation tasks. +This package is not for trivial one-line edits, is not for pure explanation tasks, is not for root-state refresh, is not for packet compression, and is not for suite bootstrap. +Treat it as an optional operational checkpoint for risky edits. ## Related Skills -- `skill-context-keeper` for rebuilding task state before or after meaningful work +- `skill-context-keeper` for rebuilding root task state before or after meaningful work +- `skill-subtask-context` for bounded child-task state +- `skill-context-packet` for packet-sized next-turn context - `skill-handoff-summary` for pause and transfer notes - `skill-task-continuity` for first-time setup and suite-level routing @@ -71,5 +77,5 @@ Replace `/path/to/install-skill-from-github.py` with the actual path to your loc python3 /path/to/install-skill-from-github.py \ --repo Golden-Promise/codex-skill-library \ --path skills/skill-phase-gate \ - --ref v0.6.1 + --ref ``` diff --git a/skills/skill-phase-gate/README.zh-CN.md b/skills/skill-phase-gate/README.zh-CN.md index d4ddc02..e9cef7b 100644 --- a/skills/skill-phase-gate/README.zh-CN.md +++ b/skills/skill-phase-gate/README.zh-CN.md @@ -4,8 +4,8 @@ ## 概述 -`skill-phase-gate` 用于在有分量的编码工作前后加入紧凑的 preflight / postflight 检查点。 -如果“加一道检查点”这件事本身就有价值，就该用它。 +`skill-phase-gate` 用于在有分量的编码工作前后加入一个 optional operational checkpoint。 +如果这道检查点对 risky edits 本身有价值，就该用它。 ## 30 秒快速开始 @@ -24,7 +24,7 @@ 你可以直接这样对 Codex 说： - `请用 skill-installer 从 Golden-Promise/codex-skill-library 的 skills/skill-phase-gate 安装 skill-phase-gate。` -- `请用 skill-installer 从 Golden-Promise/codex-skill-library 的 skills/skill-phase-gate 安装 skill-phase-gate，并使用 ref v0.6.1。` +- `请用 skill-installer 从 Golden-Promise/codex-skill-library 的 skills/skill-phase-gate 安装 skill-phase-gate，并使用 ref 。` 如果你想看精确的 shell 命令，可以直接跳到后面的 [安装细节](#安装细节)。 @@ -42,13 +42,19 @@ - 这次改动只是一个琐碎的一行编辑 - 这次工作只是纯解释、纯说明 - 当前真正的问题是任务状态过旧，而不是检查点缺失 +- 当前真正的问题是 root-state refresh，而不是检查点缺失 +- 当前真正的问题是 packet compression，而不是检查点缺失 +- 当前真正的问题是 suite bootstrap，而不是检查点缺失 - 你需要的是暂停或转交 handoff，而不是流程检查点 -这个包不适合 trivial one-line edits，也不适合 pure explanation tasks。 +这个包不适合 trivial one-line edits，也不适合 pure explanation tasks，也不适合 root-state refresh、packet compression 或 suite bootstrap。 +把它当成面向 risky edits 的 optional operational checkpoint 即可。 ## 相关技能 -- `skill-context-keeper`：适合在重要工作前后重建任务状态 +- `skill-context-keeper`：适合在重要工作前后重建 root 任务状态 +- `skill-subtask-context`：适合维护边界清楚的子任务状态 +- `skill-context-packet`：适合压缩 packet-sized 的下一轮上下文 - `skill-handoff-summary`：适合暂停或转交时写 handoff - `skill-task-continuity`：适合第一次搭建整套流程和做套件级路由 @@ -71,5 +77,5 @@ python3 /path/to/install-skill-from-github.py \ --repo Golden-Promise/codex-skill-library \ --path skills/skill-phase-gate \ - --ref v0.6.1 + --ref ``` diff --git a/skills/skill-phase-gate/SKILL.md b/skills/skill-phase-gate/SKILL.md index da65060..321e951 100644 --- a/skills/skill-phase-gate/SKILL.md +++ b/skills/skill-phase-gate/SKILL.md @@ -7,8 +7,8 @@ description: Use when a meaningful coding checkpoint is needed before or after r ## Overview -Use `skill-phase-gate` to add a compact preflight or postflight checkpoint around meaningful coding work. -It is for operational checkpoints before or after execution, not for task-state ownership, generic planning, or final handoff writing. +Use `skill-phase-gate` to add an optional operational checkpoint around meaningful coding work. +It is for risky edits before or after execution, not for root-state refresh, packet compression, suite bootstrap, generic planning, or final handoff writing. ## Use This Skill When @@ -22,6 +22,8 @@ It is for operational checkpoints before or after execution, not for task-state - the request is a typo fix, tiny one-line edit, or similarly trivial change - the user only wants an explanation, walkthrough, or analysis with no checkpoint artifact - the main need is reconstructing current task state or preserving long-running state ownership +- the main need is packet compression for the next live turn +- the main need is suite bootstrap or routing - the main need is generating a full transfer packet or final handoff summary ## Meaningful Checkpoint Bar @@ -34,8 +36,10 @@ This package is a good fit when the checkpoint serves a meaningful workflow boun ## Package Boundary - `skill-phase-gate` can mention current task state only to support the immediate checkpoint -- `skill-context-keeper` remains the owner of structured ongoing state and refreshes -- this package does not replace planning packages, and it does not become a handoff generator +- `skill-context-keeper` remains the owner of root-state refresh and compression +- `skill-subtask-context` remains the owner of local child-task state +- `skill-context-packet` remains the owner of packet-sized next-turn context +- this package does not replace suite bootstrap, planning packages, or handoff generation ## References diff --git a/skills/skill-phase-gate/agents/openai.yaml b/skills/skill-phase-gate/agents/openai.yaml index 640ba21..b3c1108 100644 --- a/skills/skill-phase-gate/agents/openai.yaml +++ b/skills/skill-phase-gate/agents/openai.yaml @@ -1,4 +1,4 @@ interface: display_name: "Skill Phase Gate" short_description: "Add meaningful preflight or postflight checkpoints to substantial coding work" - default_prompt: "Use $skill-phase-gate when the task needs a meaningful checkpoint before or after execution. Start from the task at hand, choose either a compact preflight or postflight gate, keep the output checklist-oriented, and avoid using this package for trivial one-line edits, pure explanation requests, long-term state ownership, or final handoff generation." + default_prompt: "Use $skill-phase-gate when the task needs an optional operational checkpoint before or after a risky edit. Start from the task at hand, choose either a compact preflight or postflight gate, keep the output checklist-oriented, and avoid using this package for trivial one-line edits, pure explanation requests, root-state refresh, packet compression, suite bootstrap, long-term state ownership, or final handoff generation." diff --git a/skills/skill-phase-gate/references/prompt-templates.en.md b/skills/skill-phase-gate/references/prompt-templates.en.md index b7c133d..24efe89 100644 --- a/skills/skill-phase-gate/references/prompt-templates.en.md +++ b/skills/skill-phase-gate/references/prompt-templates.en.md @@ -1,7 +1,7 @@ # skill-phase-gate Prompt Templates -Use these prompts when you want a crisp checkpoint around meaningful coding work. -If you need durable task-state ownership too, keep that with `skill-context-keeper`. +Use these prompts when you want a crisp optional operational checkpoint around meaningful coding work. +If you need durable root-state ownership, subtask-local state, or packet compression too, keep those with sibling packages. ## Positive Trigger Prompts @@ -12,6 +12,8 @@ If you need durable task-state ownership too, keep that with `skill-context-keep - `Skip the checkpoint and just fix this one-line typo.` - `Explain the code only; do not create a checkpoint artifact.` +- `Refresh the root task state instead of adding a gate.` +- `Compress the next turn into a packet instead of adding a gate.` ## Preflight Template Prompt @@ -21,7 +23,9 @@ Capture the current goal, current constraints, expected files or modules to chan files or modules explicitly not changing, and the verification plan. Keep it brief, checklist-oriented, and task-first. Do not turn this into generic planning or long-term state tracking. -If durable task-state ownership is needed, leave that to skill-context-keeper. +If durable root-state ownership is needed, leave that to skill-context-keeper. +If subtask-local state is needed, leave that to skill-subtask-context. +If packet compression is needed, leave that to skill-context-packet. ``` ## Postflight Template Prompt @@ -31,7 +35,7 @@ Use skill-phase-gate to create a postflight gate for this meaningful coding task Capture the actual files or modules changed, the actual validations run, remaining risks, and whether handoff is recommended. Keep it operational and brief. -Do not turn this into a final handoff package, and do not take over state ownership from skill-context-keeper. +Do not turn this into a final handoff package, and do not take over root-state ownership from skill-context-keeper, subtask state from skill-subtask-context, or packet compression from skill-context-packet. ``` ## Trivial Change Anti-Example diff --git a/skills/skill-phase-gate/references/prompt-templates.zh-CN.md b/skills/skill-phase-gate/references/prompt-templates.zh-CN.md index a1f02fd..7f0454d 100644 --- a/skills/skill-phase-gate/references/prompt-templates.zh-CN.md +++ b/skills/skill-phase-gate/references/prompt-templates.zh-CN.md @@ -1,7 +1,7 @@ # skill-phase-gate 提示词模板 -当你想在有分量的编码工作前后加一道简洁检查点时，可直接使用这些模板。 -如果还需要持续持有任务状态，请继续交给 `skill-context-keeper`。 +当你想在有分量的编码工作前后加一道简洁的 optional operational checkpoint 时，可直接使用这些模板。 +如果还需要持续持有 root 状态、subtask 状态或 packet compression，请继续交给兄弟包。 ## 适用触发示例 @@ -12,6 +12,8 @@ - `别加检查点了，直接把这一行 typo 改掉。` - `只解释代码，不要生成检查点产物。` +- `先刷新根任务状态，不要加 gate。` +- `把下一轮压成 packet，不要加 gate。` ## Preflight 模板提示词 @@ -21,7 +23,9 @@ 明确不会改动的文件或模块，以及验证计划。 保持简短、可执行、清单化。 不要把它扩展成泛化规划，也不要接管长期状态跟踪。 -如果需要持续状态归属，请交给 skill-context-keeper。 +如果需要持续的 root 状态归属，请交给 skill-context-keeper。 +如果需要 subtask local state，请交给 skill-subtask-context。 +如果需要 packet compression，请交给 skill-context-packet。 ``` ## Postflight 模板提示词 @@ -31,7 +35,7 @@ 内容要覆盖实际改动的文件或模块、实际运行的验证、 剩余风险，以及是否建议交接。 保持简短、偏执行视角。 -不要把它扩展成最终交接包，也不要从 skill-context-keeper 手里接管状态归属。 +不要把它扩展成最终交接包，也不要从 skill-context-keeper、skill-subtask-context 或 skill-context-packet 手里接管状态归属。 ``` ## 琐碎改动反例 diff --git a/skills/skill-phase-gate/references/use-cases.md b/skills/skill-phase-gate/references/use-cases.md index a120199..d1b8608 100644 --- a/skills/skill-phase-gate/references/use-cases.md +++ b/skills/skill-phase-gate/references/use-cases.md @@ -1,7 +1,7 @@ # skill-phase-gate Use Cases -`skill-phase-gate` is for meaningful checkpoints around substantial coding work. -Use it for a compact preflight before risky execution or a compact postflight after a meaningful edit, while leaving long-term task state with `skill-context-keeper`. +`skill-phase-gate` is for optional operational checkpoints around substantial coding work. +Use it for a compact preflight before risky execution or a compact postflight after a meaningful edit, while leaving root-state refresh, subtask state, and packet compression to sibling packages. ## Positive Trigger Prompts @@ -15,6 +15,9 @@ Use it for a compact preflight before risky execution or a compact postflight af - `Fix this typo in one line and move on.` - `Explain how this package works without generating any checkpoint artifact.` - `Refresh the current task state and keep an ongoing summary for the next hour of work.` +- `Refresh the root task state before we keep coding.` +- `Compress the next turn into a small packet instead of creating a gate.` +- `Bootstrap the whole continuity suite in this repo.` - `Write the final handoff package for the next agent taking over.` ## Common Use Cases @@ -44,5 +47,7 @@ The postflight gate is a checkpoint, not a replacement for a final handoff packa ## State Ownership Boundary -If the thread also needs durable task-state ownership, keep that with `skill-context-keeper`. +If the thread also needs durable root-state ownership, keep that with `skill-context-keeper`. +If the thread needs subtask-local state, use `skill-subtask-context`. +If the thread needs packet-sized next-turn context, use `skill-context-packet`. `skill-phase-gate` may mention the current state briefly inside the checkpoint, but it does not own the running task record. diff --git a/skills/skill-phase-gate/references/use-cases.zh-CN.md b/skills/skill-phase-gate/references/use-cases.zh-CN.md index da78df9..1683998 100644 --- a/skills/skill-phase-gate/references/use-cases.zh-CN.md +++ b/skills/skill-phase-gate/references/use-cases.zh-CN.md @@ -1,7 +1,7 @@ # skill-phase-gate 使用场景 -`skill-phase-gate` 适用于围绕有分量的编码工作增加检查点。 -它可以在高风险执行前提供紧凑的 preflight，也可以在完成一次有意义的修改后提供紧凑的 postflight；长期任务状态仍由 `skill-context-keeper` 持有。 +`skill-phase-gate` 适用于围绕有分量的编码工作增加一个 optional operational checkpoint。 +它可以在高风险执行前提供紧凑的 preflight，也可以在完成一次有意义的修改后提供紧凑的 postflight；root-state refresh、subtask state 和 packet compression 仍由其他包持有。 ## 适用触发示例 @@ -15,6 +15,9 @@ - `把这个 typo 改掉就行，只有一行。` - `只解释一下这个包怎么用，不要生成任何检查点产物。` - `刷新当前任务状态，并在接下来一小时持续维护摘要。` +- `先刷新根任务状态，再继续实现。` +- `把下一轮压成一个很小的 packet，而不是生成 gate。` +- `第一次在这个仓库里启动整套连续性工具链。` - `给下一个接手的 agent 写最终交接包。` ## 常见使用方式 @@ -44,5 +47,7 @@ postflight gate 只是检查点，不替代最终交接包。 ## 状态归属边界 -如果线程还需要持续维护任务状态，请继续交给 `skill-context-keeper`。 +如果线程还需要持续维护 root 任务状态，请继续交给 `skill-context-keeper`。 +如果线程需要 subtask local state，请交给 `skill-subtask-context`。 +如果线程需要 packet-sized 的下一轮上下文，请交给 `skill-context-packet`。 `skill-phase-gate` 可以在检查点里简短提到当前状态，但不拥有长期任务记录。 diff --git a/skills/skill-phase-gate/tests/test_package_contract.py b/skills/skill-phase-gate/tests/test_package_contract.py index 4f01309..38378ed 100644 --- a/skills/skill-phase-gate/tests/test_package_contract.py +++ b/skills/skill-phase-gate/tests/test_package_contract.py @@ -48,6 +48,14 @@ def test_readme_rules_out_trivial_or_explanation_only_usage(self): text = (ROOT / "README.md").read_text(encoding="utf-8").lower() self.assertIn("not for trivial one-line edits", text) self.assertIn("not for pure explanation tasks", text) + self.assertIn("not for root-state refresh", text) + self.assertIn("not for packet compression", text) + self.assertIn("not for suite bootstrap", text) + + def test_readme_describes_optional_checkpoint_boundary(self): + text = (ROOT / "README.md").read_text(encoding="utf-8").lower() + self.assertIn("optional operational checkpoint", text) + self.assertIn("risky edits", text) def test_readme_includes_direct_natural_language_usage(self): text = (ROOT / "README.md").read_text(encoding="utf-8").lower() @@ -69,6 +77,8 @@ def test_readme_has_fast_entry_sections(self): self.assertIn("POSTFLIGHT.template.md", text) self.assertIn("Try this first:", text) self.assertIn("Use skill-phase-gate", text) + self.assertIn("skill-context-packet", text) + self.assertIn("skill-subtask-context", text) def test_chinese_readme_has_fast_entry_sections(self): text = (ROOT / "README.zh-CN.md").read_text(encoding="utf-8") @@ -85,6 +95,8 @@ def test_chinese_readme_has_fast_entry_sections(self): self.assertIn("POSTFLIGHT.template.md", text) self.assertIn("先这样对 Codex 说：", text) self.assertIn("请用 skill-phase-gate", text) + self.assertIn("skill-context-packet", text) + self.assertIn("skill-subtask-context", text) if __name__ == "__main__": diff --git a/skills/skill-subtask-context/README.md b/skills/skill-subtask-context/README.md new file mode 100644 index 0000000..f59e9a5 --- /dev/null +++ b/skills/skill-subtask-context/README.md @@ -0,0 +1,78 @@ +# skill-subtask-context + +[简体中文](README.zh-CN.md) + +## Overview + +`skill-subtask-context` is the narrow package for opening, refreshing, and closing local child-task state during a larger long-running task. +Use it when a bounded workstream deserves its own state file instead of polluting the root task summary. + +## Start Here In 30 Seconds + +- Use this when: a child task needs its own local context, scope, and exit criteria. +- You'll get: a focused subtask state file with parent links, local facts, local risks, and merge notes. +- Typical output: updates `.agent-state/subtasks//TASK_STATE.md`. + +If you want to tell Codex exactly what to do: + +Try this first: + +- `Use skill-subtask-context to open or refresh a child task at .agent-state/subtasks//TASK_STATE.md and keep the parent context minimal.` + +## Install + +You can ask Codex in natural language: + +- `Use skill-installer to install skill-subtask-context from Golden-Promise/codex-skill-library at skills/skill-subtask-context.` +- `Use skill-installer to install skill-subtask-context from Golden-Promise/codex-skill-library at skills/skill-subtask-context using ref .` + +If you want the exact shell command, jump to [Install Details](#install-details). + +## What File Will This Create Or Update? + +The typical downstream file is `.agent-state/subtasks//TASK_STATE.md`. + +Use this package when you want to open or refresh that local subtask state so the next turn can resume from a trusted summary of: + +- the subtask objective +- the parent facts that still matter locally +- local files and inputs worth loading +- local risks, blockers, and exit criteria +- merge notes for the parent task + +## Don't Use This When + +- you need to refresh the root task state instead of a child task +- you need packet compression instead of a local state refresh +- you need a preflight or postflight checkpoint around a risky change +- you need a pause or transfer handoff rather than active local state + +This package owns local child-task state, does not own root task state, and does not own packet compression. + +## Related Skills + +- `skill-context-keeper` for `.agent-state/root/TASK_STATE.md` +- `skill-context-packet` for root or subtask packet compression +- `skill-phase-gate` for meaningful preflight and postflight checkpoints +- `skill-handoff-summary` for pause and transfer notes +- `skill-task-continuity` for suite-level bootstrap and routing + +## Documentation + +- Trigger routing and package boundary: `SKILL.md` +- Use cases and trigger examples: [references/use-cases.md](references/use-cases.md) +- Chinese use cases: [references/use-cases.zh-CN.md](references/use-cases.zh-CN.md) +- 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) +- Subtask-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-subtask-context \ + --ref +``` diff --git a/skills/skill-subtask-context/README.zh-CN.md b/skills/skill-subtask-context/README.zh-CN.md new file mode 100644 index 0000000..d6976b1 --- /dev/null +++ b/skills/skill-subtask-context/README.zh-CN.md @@ -0,0 +1,78 @@ +# skill-subtask-context + +[English](README.md) + +## 概述 + +`skill-subtask-context` 是一个窄边界包，专门负责在较大的长任务内部打开、刷新和关闭子任务的局部状态。 +当某段工作值得拥有独立状态文件，而不应该继续污染根任务摘要时，就用它。 + +## 30 秒快速开始 + +- 什么时候用：某个子任务需要独立局部上下文、独立范围和明确的退出条件。 +- 你会得到什么：一份聚焦的子任务状态文件，里面包含父任务链接、局部事实、局部风险和合并备注。 +- 典型产物：更新 `.agent-state/subtasks//TASK_STATE.md`。 + +如果你想直接告诉 Codex 怎么做： + +先这样对 Codex 说： + +- `请用 skill-subtask-context 打开或刷新一个子任务，把内容写到 .agent-state/subtasks//TASK_STATE.md，并保持父任务上下文最小化。` + +## 安装 + +你可以直接用自然语言让 Codex 安装： + +- `请用 skill-installer 从 Golden-Promise/codex-skill-library 的 skills/skill-subtask-context 安装 skill-subtask-context。` +- `请用 skill-installer 从 Golden-Promise/codex-skill-library 的 skills/skill-subtask-context 安装 skill-subtask-context，并固定到 。` + +如果你想看精确的 shell 命令，可以直接跳到 [安装细节](#安装细节)。 + +## 会创建或更新什么文件？ + +典型的下游文件是 `.agent-state/subtasks//TASK_STATE.md`。 + +当你希望打开或刷新这份局部子任务状态时，就使用这个包，让下一轮能够从一份可信摘要继续，包括： + +- 子任务目标 +- 仍然在局部范围内有效的父任务事实 +- 值得优先加载的局部文件和输入 +- 局部风险、阻塞点和退出条件 +- 合并回父任务时需要吸收的备注 + +## 不适合什么时候用 + +- 你真正需要的是刷新 root task state，而不是子任务 +- 你真正需要的是 packet compression，而不是局部状态刷新 +- 你需要高风险改动前后的检查点 +- 你需要的是暂停或转交 handoff，而不是活跃子任务状态 + +这个包负责 local child-task state，不负责 root task state，也不负责 packet compression。 + +## 相关技能 + +- `skill-context-keeper`：处理 `.agent-state/root/TASK_STATE.md` +- `skill-context-packet`：处理 root 或 subtask 的 packet 压缩 +- `skill-phase-gate`：处理 preflight / postflight 检查点 +- `skill-handoff-summary`：处理暂停和转交说明 +- `skill-task-continuity`：处理套件级 bootstrap 和路由 + +## 文档 + +- 触发路由与包边界：`SKILL.md` +- 用例与触发示例：[references/use-cases.zh-CN.md](references/use-cases.zh-CN.md) +- English use cases: [references/use-cases.md](references/use-cases.md) +- 提示词模板：[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-subtask-context \ + --ref +``` diff --git a/skills/skill-subtask-context/SKILL.md b/skills/skill-subtask-context/SKILL.md new file mode 100644 index 0000000..778aa51 --- /dev/null +++ b/skills/skill-subtask-context/SKILL.md @@ -0,0 +1,37 @@ +--- +name: skill-subtask-context +description: Use when a bounded child task needs its own local context, scope, and restart state without inflating the root task summary. +--- + +# Skill Subtask Context + +## Overview + +Use this package when a long-running task needs a child task with its own local state. +Keep the package boundary narrow: open, refresh, or close subtask state without taking over root state, packet compression, workflow gates, or final handoffs. + +## Use This Skill When + +- a child task needs its own `.agent-state/subtasks//TASK_STATE.md` +- the parent task is getting noisy and should hand a bounded slice to a separate owner +- a subtask needs local facts, local risks, and local exit criteria +- a child task is closing and its merge notes need to be made explicit + +## Do Not Use This Skill When + +- the root task state itself needs a refresh +- the next step only needs a compressed packet rather than a full local state refresh +- the task needs a risky-change checkpoint or formal gate +- the task is pausing and needs a handoff summary instead of active subtask state + +## Package Boundary + +This package owns local child-task state such as `.agent-state/subtasks//TASK_STATE.md`. +It does not own root task state, does not own packet compression, does not own workflow gates, and does not own final handoffs. + +## References + +- `README.md` and `README.zh-CN.md`: entry docs and direct invocation wording +- `references/use-cases.md`: positive and negative trigger examples +- `references/prompt-templates.en.md`: reusable prompt patterns +- `assets/TASK_STATE.template.md`: subtask-state template diff --git a/skills/skill-subtask-context/agents/openai.yaml b/skills/skill-subtask-context/agents/openai.yaml new file mode 100644 index 0000000..c6a8000 --- /dev/null +++ b/skills/skill-subtask-context/agents/openai.yaml @@ -0,0 +1,4 @@ +interface: + display_name: "Skill Subtask Context" + short_description: "Maintain isolated child-task state without inflating root context" + default_prompt: "Use $skill-subtask-context when a bounded child task needs its own local state: open or refresh .agent-state/subtasks//TASK_STATE.md, keep only the necessary parent facts, capture local scope, risks, and exit criteria, and avoid taking over root-state refresh, packet compression, workflow gates, or final handoffs." diff --git a/skills/skill-subtask-context/assets/TASK_STATE.template.md b/skills/skill-subtask-context/assets/TASK_STATE.template.md new file mode 100644 index 0000000..4595c03 --- /dev/null +++ b/skills/skill-subtask-context/assets/TASK_STATE.template.md @@ -0,0 +1,40 @@ +# Subtask State + +## Subtask Objective +- State the bounded child task in one sentence. +- Keep it tied to one parent task outcome. + +## Parent Context +- Link back to the parent task or packet. +- Record only the parent facts this subtask must preserve. + +## Local Scope / Non-Goals +- List what this subtask owns. +- Mark adjacent work that stays with the parent task or another subtask. + +## Inputs To Load +- Name the files, commands, and artifacts this subtask needs first. +- Keep the list minimal. + +## Local Facts +- Record verified facts discovered inside this subtask. +- Avoid duplicating unchanged parent state. + +## Open Risks / Blockers +- Capture blockers, unknowns, or fragile areas local to this subtask. +- Escalate cross-cutting risks back to the parent task. + +## Exit Criteria +- List the conditions for closing or merging this subtask. +- Make the criteria observable. + +## Next Recommended Action +- State the next local action. +- Keep it small enough for one short turn. + +## Verification Still Needed +- List checks that remain for this subtask. +- Separate missing verification from failed verification. + +## Merge / Closure Notes +- Record what the parent task should absorb when this subtask finishes. diff --git a/skills/skill-subtask-context/references/README.md b/skills/skill-subtask-context/references/README.md new file mode 100644 index 0000000..be4ed22 --- /dev/null +++ b/skills/skill-subtask-context/references/README.md @@ -0,0 +1,4 @@ +# skill-subtask-context References + +- [use-cases.md](use-cases.md): positive and negative trigger examples +- [prompt-templates.en.md](prompt-templates.en.md): reusable prompt patterns for opening or refreshing child-task state diff --git a/skills/skill-subtask-context/references/README.zh-CN.md b/skills/skill-subtask-context/references/README.zh-CN.md new file mode 100644 index 0000000..0e282d6 --- /dev/null +++ b/skills/skill-subtask-context/references/README.zh-CN.md @@ -0,0 +1,4 @@ +# skill-subtask-context 参考资料 + +- [use-cases.zh-CN.md](use-cases.zh-CN.md)：适用与不适用触发示例 +- [prompt-templates.zh-CN.md](prompt-templates.zh-CN.md)：打开或刷新子任务状态时可复用的提示词模板 diff --git a/skills/skill-subtask-context/references/prompt-templates.en.md b/skills/skill-subtask-context/references/prompt-templates.en.md new file mode 100644 index 0000000..27046d8 --- /dev/null +++ b/skills/skill-subtask-context/references/prompt-templates.en.md @@ -0,0 +1,36 @@ +# skill-subtask-context Prompt Templates + +Use these templates when you want `skill-subtask-context` to open or refresh isolated child-task state without drifting into root-state refresh, packet compression, gates, or handoffs. + +## Positive Trigger Prompts + +- `Use skill-subtask-context to open a child task for this bounded workstream.` +- `Refresh the local state at .agent-state/subtasks//TASK_STATE.md and keep only the parent facts that still matter.` +- `Update the subtask objective, local blockers, exit criteria, and merge notes before we continue.` + +## Negative Trigger Prompts + +- `Refresh the root task summary before the next turn.` +- `Compress the next turn into a packet.` +- `Gate this risky change before implementation.` +- `Write the pause handoff for the next owner.` + +## Open a New Child Task + +```text +Use skill-subtask-context to open a child task. +Write or refresh .agent-state/subtasks//TASK_STATE.md, +copy in only the parent facts that the child task must preserve, +define local scope, local risks, exit criteria, and the next recommended action, +and keep the boundary narrow: local child-task state only. +``` + +## Refresh an Existing Child Task + +```text +Refresh the local state for this child task without rewriting the full root task. +Assume the downstream artifact lives at .agent-state/subtasks//TASK_STATE.md. +Capture parent context that still matters locally, new verified facts, blockers, +verification still needed, and merge / closure notes for the parent task. +Do not compress a packet or generate a handoff. +``` diff --git a/skills/skill-subtask-context/references/prompt-templates.zh-CN.md b/skills/skill-subtask-context/references/prompt-templates.zh-CN.md new file mode 100644 index 0000000..b40f604 --- /dev/null +++ b/skills/skill-subtask-context/references/prompt-templates.zh-CN.md @@ -0,0 +1,36 @@ +# skill-subtask-context 提示词模板 + +当你希望 `skill-subtask-context` 打开或刷新隔离的子任务局部状态，而不是去处理 root-state refresh、packet compression、gate 或 handoff 时，可以使用这些模板。 + +## 适用触发示例 + +- `请用 skill-subtask-context 为这段边界清楚的工作打开一个子任务。` +- `请刷新 .agent-state/subtasks//TASK_STATE.md，只保留仍然对这个子任务有效的父任务事实。` +- `在继续之前，先更新这个子任务的目标、局部阻塞点、退出条件和 merge notes。` + +## 不适用触发示例 + +- `在下一轮之前先刷新根任务摘要。` +- `把下一轮压缩成一个 packet。` +- `在实现前给这个高风险改动加一个 gate。` +- `给下一位 owner 写暂停 handoff。` + +## 打开一个新子任务 + +```text +请用 skill-subtask-context 打开一个子任务。 +写入或刷新 .agent-state/subtasks//TASK_STATE.md， +只复制这个子任务必须继承的父任务事实， +定义局部范围、局部风险、退出条件和下一步建议动作， +并保持边界收敛：只处理 local child-task state。 +``` + +## 刷新一个已有子任务 + +```text +请刷新这个子任务的局部状态，不要重写整份根任务。 +假设下游工件位于 .agent-state/subtasks//TASK_STATE.md。 +记录仍然在局部范围内有效的父任务上下文、新验证的事实、阻塞点、 +仍需验证的内容，以及回流给父任务的 merge / closure notes。 +不要顺手压 packet，也不要生成 handoff。 +``` diff --git a/skills/skill-subtask-context/references/use-cases.md b/skills/skill-subtask-context/references/use-cases.md new file mode 100644 index 0000000..04a6073 --- /dev/null +++ b/skills/skill-subtask-context/references/use-cases.md @@ -0,0 +1,38 @@ +# skill-subtask-context Use Cases + +`skill-subtask-context` is for maintaining isolated local child-task state during a larger task. +Use it when the work should split into a bounded subtask instead of stretching the root task summary further. + +## Positive Trigger Prompts + +- `Use skill-subtask-context to open a child task for the parser cleanup and write .agent-state/subtasks/parser-cleanup/TASK_STATE.md.` +- `Refresh the local state for the api-migration subtask without rewriting the full root task.` +- `This workstream needs its own owner, local risks, and exit criteria. Open a subtask state file for it.` +- `Capture the parent facts that still matter locally and keep the rest out of the child task.` +- `Close this child task by updating its merge notes and next recommended action.` + +## Negative Trigger Prompts + +- `Refresh the overall root task summary before we continue.` +- `Compress the next turn into a tiny packet instead of a full state file.` +- `Run a preflight gate before this risky refactor starts.` +- `Write the pause handoff for the next agent taking over this work.` +- `Bootstrap the whole continuity suite in a repository for the first time.` + +## Subtask State Wording Patterns + +Use wording like this when the request is specifically about local child-task state: + +- `Open a child task for this bounded slice of work.` +- `Refresh the local subtask state without restating the whole parent task.` +- `Keep only the parent facts that this subtask must preserve.` +- `Record merge notes for the parent task before closing the child task.` + +## Typical Output Shape + +The package usually refreshes a compact state artifact such as `.agent-state/subtasks//TASK_STATE.md` with: + +- the subtask objective and local scope +- parent context worth preserving locally +- local facts, blockers, and exit criteria +- the next recommended action and merge notes diff --git a/skills/skill-subtask-context/references/use-cases.zh-CN.md b/skills/skill-subtask-context/references/use-cases.zh-CN.md new file mode 100644 index 0000000..549de27 --- /dev/null +++ b/skills/skill-subtask-context/references/use-cases.zh-CN.md @@ -0,0 +1,38 @@ +# skill-subtask-context 用例 + +`skill-subtask-context` 用于在更大的长任务内部维护隔离的子任务局部状态。 +当工作应该切成一个边界清楚的子任务，而不是继续拉长 root task summary 时，就应该触发它。 + +## 适用触发示例 + +- `请用 skill-subtask-context 为 parser-cleanup 打开一个子任务，并写入 .agent-state/subtasks/parser-cleanup/TASK_STATE.md。` +- `请刷新 api-migration 这个子任务的局部状态，但不要重写整个根任务。` +- `这段工作需要独立 owner、局部风险和退出条件，请为它建立子任务状态文件。` +- `只保留这个子任务必须继承的父任务事实，其他内容不要重复。` +- `在关闭这个子任务前，把需要回流给父任务的 merge notes 写清楚。` + +## 不适用触发示例 + +- `在继续之前先刷新整个根任务摘要。` +- `把下一轮压成一个很小的 packet，不要写完整状态文件。` +- `在这个高风险重构开始前先跑一次 preflight gate。` +- `给下一位接手者写暂停 handoff。` +- `第一次在仓库里启动整套连续性工具链。` + +## 子任务状态措辞模式 + +当需求明确是“局部子任务状态”时，可以使用这类措辞： + +- `为这段边界清楚的工作打开一个子任务。` +- `刷新这个子任务的局部状态，不要重复整个父任务。` +- `只保留这个子任务必须继承的父任务事实。` +- `在关闭子任务前，把 merge notes 留给父任务。` + +## 典型输出形态 + +这个包通常会刷新一份紧凑的状态工件，例如 `.agent-state/subtasks//TASK_STATE.md`，其中包括： + +- 子任务目标和局部范围 +- 需要局部保留的父任务上下文 +- 局部事实、阻塞点和退出条件 +- 下一步建议动作和 merge notes diff --git a/skills/skill-subtask-context/tests/test_package_contract.py b/skills/skill-subtask-context/tests/test_package_contract.py new file mode 100644 index 0000000..e509ebc --- /dev/null +++ b/skills/skill-subtask-context/tests/test_package_contract.py @@ -0,0 +1,109 @@ +from pathlib import Path +import unittest + + +ROOT = Path(__file__).resolve().parents[1] + + +class SkillSubtaskContextPackageTests(unittest.TestCase): + def test_skill_frontmatter_name(self): + text = (ROOT / "SKILL.md").read_text(encoding="utf-8") + self.assertIn("name: skill-subtask-context", text) + + def test_core_package_files_exist(self): + for path in [ + ROOT / "README.md", + ROOT / "README.zh-CN.md", + ROOT / "SKILL.md", + ROOT / "agents" / "openai.yaml", + ROOT / "references" / "README.md", + ROOT / "references" / "README.zh-CN.md", + ROOT / "references" / "use-cases.md", + ROOT / "references" / "use-cases.zh-CN.md", + ROOT / "references" / "prompt-templates.en.md", + ROOT / "references" / "prompt-templates.zh-CN.md", + ROOT / "assets" / "TASK_STATE.template.md", + ]: + self.assertTrue(path.exists(), f"expected package file to exist: {path}") + + def test_subtask_state_template_has_required_sections(self): + text = (ROOT / "assets" / "TASK_STATE.template.md").read_text(encoding="utf-8") + for heading in [ + "# Subtask State", + "## Subtask Objective", + "## Parent Context", + "## Local Scope / Non-Goals", + "## Inputs To Load", + "## Local Facts", + "## Open Risks / Blockers", + "## Exit Criteria", + "## Next Recommended Action", + "## Verification Still Needed", + "## Merge / Closure Notes", + ]: + self.assertIn(heading, text) + + def test_bilingual_use_cases_include_trigger_sections(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") + + self.assertRegex(english, r"(?im)^## +Positive Trigger Prompts$") + self.assertRegex(english, r"(?im)^## +Negative Trigger Prompts$") + self.assertRegex(chinese, r"(?m)^## +适用触发示例$") + self.assertRegex(chinese, r"(?m)^## +不适用触发示例$") + + def test_readme_describes_subtask_boundary(self): + text = (ROOT / "README.md").read_text(encoding="utf-8").lower() + self.assertIn("local child-task state", text) + self.assertIn("does not own root task state", text) + self.assertIn("does not own packet compression", 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-subtask-context to open or refresh a child task", + text, + ) + + def test_readme_has_fast_entry_sections(self): + text = (ROOT / "README.md").read_text(encoding="utf-8") + for heading in [ + "## Start Here In 30 Seconds", + "## Install", + "## What File Will This Create Or Update?", + "## Don't Use This When", + "## Related Skills", + ]: + self.assertIn(heading, text) + self.assertIn("Typical output:", text) + self.assertIn(".agent-state/subtasks//TASK_STATE.md", text) + self.assertIn("Try this first:", text) + self.assertIn("Use skill-subtask-context", text) + + def test_chinese_readme_has_fast_entry_sections(self): + text = (ROOT / "README.zh-CN.md").read_text(encoding="utf-8") + for heading in [ + "## 30 秒快速开始", + "## 安装", + "## 会创建或更新什么文件？", + "## 不适合什么时候用", + "## 相关技能", + ]: + self.assertIn(heading, text) + self.assertIn("典型产物：", text) + self.assertIn(".agent-state/subtasks//TASK_STATE.md", text) + self.assertIn("先这样对 Codex 说：", text) + self.assertIn("请用 skill-subtask-context", 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") + + for text in [english, chinese]: + self.assertIn("use-cases", text) + self.assertIn("prompt-templates", text) + + +if __name__ == "__main__": + unittest.main() diff --git a/skills/skill-task-continuity/README.md b/skills/skill-task-continuity/README.md index e3fa095..2e35c49 100644 --- a/skills/skill-task-continuity/README.md +++ b/skills/skill-task-continuity/README.md @@ -10,8 +10,8 @@ Start here if you are setting up the continuity workflow in a project for the fi ## Start Here In 30 Seconds - Use this when: you want to set up the continuity workflow in a repo, understand the suite, or decide which continuity skill to use next. -- You'll get: starter files for a downstream repo, a simple long-task loop, and a clear route to the atomic skills. -- Typical output: a downstream `AGENTS.md` plus `.agent-state/` starter files. +- You'll get: starter files for a downstream repo, a packet-first long-task loop, and a clear route to the atomic skills. +- Typical output: a downstream `AGENTS.md`, `.agent-state/INDEX.md`, and layered root/subtask starter directories. If you want to tell Codex exactly what to do: @@ -29,10 +29,10 @@ You can ask Codex to install only this package: You can also ask Codex to install the full suite: -- `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.` +- `Use skill-installer to install the full long-task continuity suite from Golden-Promise/codex-skill-library in one command at skills/skill-context-keeper, skills/skill-subtask-context, skills/skill-context-packet, skills/skill-phase-gate, skills/skill-handoff-summary, and skills/skill-task-continuity.` Installing `skill-task-continuity` does not auto-install the atomic packages. -If you want all four packages at once, install the full suite in one command or use the full-suite natural-language prompt above. +If you want all six packages at once, install the full suite in one command or use the full-suite natural-language prompt above. If you want the exact shell commands, jump to [Install Details](#install-details). @@ -41,26 +41,47 @@ If you want the exact shell commands, jump to [Install Details](#install-details The bootstrap helper prepares downstream starter files such as: - `AGENTS.md` -- `.agent-state/TASK_STATE.md` -- `.agent-state/HANDOFF.md` -- `.agent-state/DECISIONS.md` -- `.agent-state/RUN_LOG.md` - -`TASK_STATE.md` and `HANDOFF.md` are convenience copies of the atomic package templates so a downstream repo can start quickly. +- `.agent-state/INDEX.md` +- `.agent-state/root/TASK_STATE.md` +- `.agent-state/root/PACKET.md` +- `.agent-state/root/HANDOFF.md` +- `.agent-state/root/DECISIONS.md` +- `.agent-state/root/RUN_LOG.md` +- `.agent-state/subtasks/` +- `.agent-state/archive/root/` +- `.agent-state/archive/subtasks/` +- `.agent-state/archive/packets/` + +Root `TASK_STATE.md` and `HANDOFF.md` stay aligned with the existing atomic package templates. +The suite also ships subtask and packet templates so downstream repos can expand without inventing a second workflow. ## Fastest Setup After installation, the fastest setup path is: 1. Ask Codex to bootstrap the starter files into your downstream repo. -2. Review the created `AGENTS.md` and `.agent-state/` files. +2. Review `AGENTS.md`, `.agent-state/INDEX.md`, and `.agent-state/root/PACKET.md`. 3. Start the first real task by calling the atomic package that owns the next action. If you need exact CLI control instead, use `python3 skills/skill-task-continuity/scripts/bootstrap_suite.py --target /path/to/downstream-repo --dry-run` first, then rerun without `--dry-run` to apply. +## Beginner Mode + +Beginner mode means you only use: + +- `.agent-state/INDEX.md` +- `.agent-state/root/TASK_STATE.md` +- `.agent-state/root/PACKET.md` +- `.agent-state/root/HANDOFF.md` + +Stay in beginner mode until you actually need a child task with its own owner or isolated local context. +Expanded mode starts when you open `.agent-state/subtasks//` and route work through `skill-subtask-context` and `skill-context-packet`. + ## Which Skill To Use Next -- Use `skill-context-keeper` when the task is active but the state picture is stale. +- Use `skill-context-keeper` when the root task is active but the state picture is stale. +- Use `skill-subtask-context` when work should move into a bounded child task with its own local state. +- Use `skill-context-packet` when the next turn needs a smaller injection surface than a full state file. - Use `skill-phase-gate` when the next step is a risky or multi-file change. - Use `skill-handoff-summary` when you are about to pause or transfer the work. @@ -71,13 +92,15 @@ If you need exact CLI control instead, use `python3 skills/skill-task-continuity - you only need a checkpoint around a meaningful change - you only need a pause or transfer note -This package does not replace the three atomic skills and does not turn this public library checkout into a consumer repo. +This package does not replace the atomic skills and does not turn this public library checkout into a consumer repo. ## Related Skills -- `skill-context-keeper` for `.agent-state/TASK_STATE.md` +- `skill-context-keeper` for `.agent-state/root/TASK_STATE.md` +- `skill-subtask-context` for `.agent-state/subtasks//TASK_STATE.md` +- `skill-context-packet` for `.agent-state/root/PACKET.md` or subtask packets - `skill-phase-gate` for preflight and postflight checkpoints -- `skill-handoff-summary` for `.agent-state/HANDOFF.md` +- `skill-handoff-summary` for root or subtask handoffs ## Documentation @@ -98,7 +121,7 @@ Install only this package: python3 /path/to/install-skill-from-github.py \ --repo Golden-Promise/codex-skill-library \ --path skills/skill-task-continuity \ - --ref v0.6.1 + --ref ``` Install the full suite in one command: @@ -108,8 +131,9 @@ python3 /path/to/install-skill-from-github.py \ --repo Golden-Promise/codex-skill-library \ --path \ skills/skill-context-keeper \ + skills/skill-subtask-context \ + skills/skill-context-packet \ skills/skill-phase-gate \ skills/skill-handoff-summary \ - skills/skill-task-continuity \ - --ref v0.6.1 + skills/skill-task-continuity ``` diff --git a/skills/skill-task-continuity/README.zh-CN.md b/skills/skill-task-continuity/README.zh-CN.md index ee3b261..7eacbb4 100644 --- a/skills/skill-task-continuity/README.zh-CN.md +++ b/skills/skill-task-continuity/README.zh-CN.md @@ -10,8 +10,8 @@ ## 30 秒快速开始 - 什么时候用：你想把连续性工作流装进一个仓库、理解整套工具链，或者判断下一步该用哪个连续性技能。 -- 你会得到什么：一组下游启动文件、一个简单的长任务循环，以及通往三个原子技能的清晰入口。 -- 典型产物：下游仓库里的 `AGENTS.md` 和 `.agent-state/` 启动文件。 +- 你会得到什么：一组下游启动文件、一个 packet-first 的长任务循环，以及通往原子技能的清晰入口。 +- 典型产物：下游仓库里的 `AGENTS.md`、`.agent-state/INDEX.md`，以及分层的 root/subtask 启动目录。 如果你想直接告诉 Codex 怎么做： @@ -29,10 +29,10 @@ 你也可以让 Codex 直接安装整套工具链： -- `请用 skill-installer 从 Golden-Promise/codex-skill-library 一次安装整套长任务连续性工具链，包括 skills/skill-context-keeper、skills/skill-phase-gate、skills/skill-handoff-summary 和 skills/skill-task-continuity。` +- `请用 skill-installer 从 Golden-Promise/codex-skill-library 一条命令一次安装整套长任务连续性工具链，包括 skills/skill-context-keeper、skills/skill-subtask-context、skills/skill-context-packet、skills/skill-phase-gate、skills/skill-handoff-summary 和 skills/skill-task-continuity。` 安装 `skill-task-continuity` 本身不会自动把另外三个原子包一起装上。 -如果你想一次拿到 4 个包，应该显式安装整套；你可以用上面的自然语言提示，也可以在后面的安装细节里用一条命令完成。 +如果你想一次拿到整套 6 个包，应该显式安装整套；你可以用上面的自然语言提示，也可以在后面的安装细节里用一条命令完成。 如果你想看精确的 shell 命令，可以直接跳到后面的 [安装细节](#安装细节)。 @@ -41,26 +41,47 @@ bootstrap helper 会为下游仓库准备这些启动文件： - `AGENTS.md` -- `.agent-state/TASK_STATE.md` -- `.agent-state/HANDOFF.md` -- `.agent-state/DECISIONS.md` -- `.agent-state/RUN_LOG.md` - -其中 `TASK_STATE.md` 和 `HANDOFF.md` 是从原子包模板复制来的便利副本，目的是让下游仓库更快起步。 +- `.agent-state/INDEX.md` +- `.agent-state/root/TASK_STATE.md` +- `.agent-state/root/PACKET.md` +- `.agent-state/root/HANDOFF.md` +- `.agent-state/root/DECISIONS.md` +- `.agent-state/root/RUN_LOG.md` +- `.agent-state/subtasks/` +- `.agent-state/archive/root/` +- `.agent-state/archive/subtasks/` +- `.agent-state/archive/packets/` + +其中 root `TASK_STATE.md` 和 `HANDOFF.md` 会继续与现有原子包模板保持一致。 +套件还会同时提供 subtask 和 packet 模板，方便下游仓库扩展，而不用再发明第二套流程。 ## 最快的开始方式 安装之后，最快的起步路径是： 1. 让 Codex 把启动文件 bootstrap 到你的下游仓库。 -2. 查看生成的 `AGENTS.md` 和 `.agent-state/` 文件。 +2. 查看生成的 `AGENTS.md`、`.agent-state/INDEX.md` 和 `.agent-state/root/PACKET.md`。 3. 真正开始做任务时，直接调用拥有“下一步动作”的原子技能。 如果你想精确控制 CLI，也可以先运行 `python3 skills/skill-task-continuity/scripts/bootstrap_suite.py --target /path/to/downstream-repo --dry-run` 预览，再去掉 `--dry-run` 正式应用。 +## Beginner Mode + +beginner mode 指的是你暂时只使用： + +- `.agent-state/INDEX.md` +- `.agent-state/root/TASK_STATE.md` +- `.agent-state/root/PACKET.md` +- `.agent-state/root/HANDOFF.md` + +只有当你真的需要一个拥有独立 owner 或独立局部上下文的子任务时，才从 beginner mode 进入 expanded mode。 +进入 expanded mode 以后，再通过 `.agent-state/subtasks//`、`skill-subtask-context` 和 `skill-context-packet` 来切分上下文。 + ## 下一步该用哪个技能 -- 当任务还在继续，但状态图景已经变旧时，用 `skill-context-keeper`。 +- 当根任务还在继续，但状态图景已经变旧时，用 `skill-context-keeper`。 +- 当工作应该切成一个边界清楚的子任务，并独立维护局部状态时，用 `skill-subtask-context`。 +- 当下一轮只需要最小注入上下文，而不该整份状态都塞进窗口时，用 `skill-context-packet`。 - 当下一步是高风险或多文件改动时，用 `skill-phase-gate`。 - 当你即将暂停或转交工作时，用 `skill-handoff-summary`。 @@ -71,13 +92,15 @@ bootstrap helper 会为下游仓库准备这些启动文件： - 你只需要给重要改动加一个检查点 - 你只需要写一份暂停或转交说明 -这个包不会替代三个原子技能，也不会把这个公共技能库工作区变成消费者仓库。 +这个包不会替代原子技能，也不会把这个公共技能库工作区变成消费者仓库。 ## 相关技能 -- `skill-context-keeper`：处理 `.agent-state/TASK_STATE.md` +- `skill-context-keeper`：处理 `.agent-state/root/TASK_STATE.md` +- `skill-subtask-context`：处理 `.agent-state/subtasks//TASK_STATE.md` +- `skill-context-packet`：处理 `.agent-state/root/PACKET.md` 或子任务 packet - `skill-phase-gate`：处理 preflight / postflight 检查点 -- `skill-handoff-summary`：处理 `.agent-state/HANDOFF.md` +- `skill-handoff-summary`：处理 root 或 subtask handoff ## 文档 @@ -98,7 +121,7 @@ bootstrap helper 会为下游仓库准备这些启动文件： python3 /path/to/install-skill-from-github.py \ --repo Golden-Promise/codex-skill-library \ --path skills/skill-task-continuity \ - --ref v0.6.1 + --ref ``` 用一条命令安装整套工具链： @@ -108,8 +131,9 @@ python3 /path/to/install-skill-from-github.py \ --repo Golden-Promise/codex-skill-library \ --path \ skills/skill-context-keeper \ + skills/skill-subtask-context \ + skills/skill-context-packet \ skills/skill-phase-gate \ skills/skill-handoff-summary \ - skills/skill-task-continuity \ - --ref v0.6.1 + skills/skill-task-continuity ``` diff --git a/skills/skill-task-continuity/SKILL.md b/skills/skill-task-continuity/SKILL.md index 5077463..67eb0a8 100644 --- a/skills/skill-task-continuity/SKILL.md +++ b/skills/skill-task-continuity/SKILL.md @@ -8,12 +8,12 @@ description: Use when the user is explicitly bootstrapping or coordinating the l ## Overview Coordinate the long-task continuity suite when the task is about the continuity workflow itself rather than a single atomic continuity action. -Use this package as the suite entry point and downstream bootstrap helper while keeping the atomic package boundaries clear. +Use this package as the suite entry point and downstream bootstrap helper while keeping root state, subtask state, packets, gates, and handoffs in separate packages. ## Use This Skill When - bootstrapping the long-task continuity suite in a downstream repository -- explaining how context refresh, phase gates, and handoff behavior fit together +- explaining how root state, subtask state, packets, phase gates, and handoff behavior fit together - deciding which atomic package should trigger first in a suite-shaped request - protecting package boundaries when a prompt mentions multiple continuity concerns @@ -27,11 +27,13 @@ Use this package as the suite entry point and downstream bootstrap helper while ## Composition Boundary This package explains the suite and bootstraps downstream templates. -It does not replace the three atomic skills: +It does not replace the atomic skills: -- `skill-context-keeper` owns ongoing task state such as `.agent-state/TASK_STATE.md` +- `skill-context-keeper` owns ongoing root task state such as `.agent-state/root/TASK_STATE.md` +- `skill-subtask-context` owns bounded child-task state under `.agent-state/subtasks/` +- `skill-context-packet` owns the minimum packet injected into the next turn - `skill-phase-gate` owns meaningful preflight and postflight checkpoints -- `skill-handoff-summary` owns `.agent-state/HANDOFF.md` and continuation-oriented handoffs +- `skill-handoff-summary` owns continuation-oriented handoffs for root or subtask pauses Use `skill-task-continuity` to route into the right atomic package or to install the downstream starter files that make the suite easy to adopt. @@ -44,6 +46,6 @@ Do not use this package to mutate the public library root into a consumer repo. ## References - `README.md` and `README.zh-CN.md`: package overview, bootstrap command, and suite entry guidance -- `references/composition-guide.md`: how the suite pieces fit together and when to invoke each atomic skill -- `references/install-playbook.md`: downstream bootstrap walkthrough and recommended layout +- `references/composition-guide.md`: packet-first routing, root vs subtask scope, and when to invoke each atomic skill +- `references/install-playbook.md`: downstream bootstrap walkthrough for `INDEX.md`, `root/`, `subtasks/`, and `archive/` - `assets/`: downstream-only templates copied by `scripts/bootstrap_suite.py` diff --git a/skills/skill-task-continuity/assets/AGENTS.repo-template.md b/skills/skill-task-continuity/assets/AGENTS.repo-template.md index 3c5722d..af264d7 100644 --- a/skills/skill-task-continuity/assets/AGENTS.repo-template.md +++ b/skills/skill-task-continuity/assets/AGENTS.repo-template.md @@ -3,16 +3,40 @@ This repository uses the long-task continuity suite as a set of narrow, composable skills. Invoke the atomic skills directly when you need continuity support; this `AGENTS.md` file explains when each one should take over. +## Entry Point + +Start from `.agent-state/INDEX.md`. +Read the root packet or a subtask packet before loading a full state file. +Treat packets as the default injection surface and state files as the deeper source of truth. + ## Atomic Skills ### Refresh task state with `skill-context-keeper` Use wording like: -- `Use $skill-context-keeper to refresh .agent-state/TASK_STATE.md before more edits.` -- `Rebuild the current task state, separate facts from assumptions, and update .agent-state/TASK_STATE.md.` +- `Use $skill-context-keeper to refresh .agent-state/root/TASK_STATE.md before more edits.` +- `Rebuild the current root task state, separate facts from assumptions, and update .agent-state/root/TASK_STATE.md.` + +Reach for this when the root thread is stale, the repo has changed since the last turn, or the next agent needs a current snapshot before acting. + +### Open or refresh a child task with `skill-subtask-context` + +Use wording like: + +- `Use $skill-subtask-context to open .agent-state/subtasks/parser-cleanup/TASK_STATE.md for this bounded child task.` +- `Refresh the local state for the parser-cleanup subtask without restating the whole parent task.` + +Use it when a child task deserves its own owner, its own narrow scope, or a local note set that should not bloat the root task state. + +### Compress the next turn with `skill-context-packet` + +Use wording like: + +- `Use $skill-context-packet to compress the next root turn into .agent-state/root/PACKET.md.` +- `Write the minimum packet for the parser-cleanup subtask before handing it off.` -Reach for this when the thread is stale, the repo has changed since the last turn, or the next agent needs a current snapshot before acting. +Use it when the next agent only needs the minimum facts, constraints, and next action, not a full state refresh. ### Gate meaningful changes with `skill-phase-gate` @@ -34,25 +58,37 @@ Use it when work is pausing, changing owners, or needs a trusted restart note fo ## Recommended Long-Task Loop -1. Read `.agent-state/TASK_STATE.md`, `.agent-state/HANDOFF.md`, and any recent notes in `.agent-state/` before resuming work. -2. If the next change is meaningful or risky, run `skill-phase-gate` first so scope, non-goals, and validation stay explicit. -3. Execute the work, then refresh `.agent-state/TASK_STATE.md` with `skill-context-keeper` so the next turn inherits verified state. -4. Record durable choices in `.agent-state/DECISIONS.md` and append session-level evidence to `.agent-state/RUN_LOG.md` when it helps future resumes. -5. If work stops or ownership changes, use `skill-handoff-summary` to refresh `.agent-state/HANDOFF.md` with status, blockers, and the exact next action. +1. Read `.agent-state/INDEX.md`, then open the root packet or the active subtask packet before touching broader state files. +2. If the packet is not enough, open the matching root or subtask state file. +3. If the next change is meaningful or risky, run `skill-phase-gate` first so scope, non-goals, and validation stay explicit. +4. Execute the work, then refresh the matching root or subtask state file so the next turn inherits verified state. +5. Compress the next action back into a packet with `skill-context-packet`. +6. Record durable choices in `.agent-state/root/DECISIONS.md` and append session-level evidence to `.agent-state/root/RUN_LOG.md` only when it helps future resumes. +7. If work stops or ownership changes, use `skill-handoff-summary` to refresh the matching handoff with status, blockers, and the exact next action. ## Recommended Downstream Layout ```text AGENTS.md .agent-state/ - TASK_STATE.md - HANDOFF.md - DECISIONS.md - RUN_LOG.md + INDEX.md + root/ + TASK_STATE.md + PACKET.md + HANDOFF.md + DECISIONS.md + RUN_LOG.md + subtasks/ + archive/ + root/ + subtasks/ + packets/ ``` These files are downstream consumer artifacts. -They are not meant to modify the public skill library itself. +Beginner mode uses `INDEX.md` and `root/` only. +Expanded mode opens real child-task folders inside `subtasks/`. +These files are not meant to modify the public skill library itself. ## Optional Repo-Local Wrappers diff --git a/skills/skill-task-continuity/assets/agent-state/INDEX.template.md b/skills/skill-task-continuity/assets/agent-state/INDEX.template.md new file mode 100644 index 0000000..40d2ec0 --- /dev/null +++ b/skills/skill-task-continuity/assets/agent-state/INDEX.template.md @@ -0,0 +1,35 @@ +# Context Index + +Use this file as the repo entry point for the context protocol. +Read it first, then open only the root or subtask packet you actually need. + +## Beginner Mode + +- Start with `.agent-state/root/PACKET.md`. +- Read `.agent-state/root/TASK_STATE.md` only when the packet is not enough. +- Stay in beginner mode when one agent owns one active task and there are no parallel subtasks yet. + +## Expanded Mode + +- Create a subtask folder under `.agent-state/subtasks/` when work splits into a bounded child task with its own owner, scope, or risk profile. +- Archive closed material under `.agent-state/archive/root/`, `.agent-state/archive/subtasks/`, or `.agent-state/archive/packets/`. +- Keep packets short and treat them as the default injection surface for the next turn. + +## Root Artifacts + +- `root/TASK_STATE.md`: durable top-level task state +- `root/PACKET.md`: minimum context to inject for the next root-level action +- `root/HANDOFF.md`: pause or transfer note for the top-level task +- `root/DECISIONS.md`: durable decisions to preserve +- `root/RUN_LOG.md`: session evidence worth keeping + +## Active Subtasks + +- Add one bullet per active subtask with its folder name, owner, and exact status. +- Point each bullet to the subtask packet first, then to deeper state only if needed. + +## Compression Rules + +- Keep packets smaller than task-state files. +- Move stale detail out of root state before it crowds out current facts. +- Prefer linking to evidence over copying long command transcripts into packets. diff --git a/skills/skill-task-continuity/assets/agent-state/root/DECISIONS.template.md b/skills/skill-task-continuity/assets/agent-state/root/DECISIONS.template.md new file mode 100644 index 0000000..eb85714 --- /dev/null +++ b/skills/skill-task-continuity/assets/agent-state/root/DECISIONS.template.md @@ -0,0 +1,23 @@ +# Decisions Log + +Record durable decisions that future sessions should preserve. +Add a new entry for each meaningful choice rather than rewriting history. + +## Entry Template + +### Decision +- Date: +- Owner: +- Status: + +### Context +- What problem or tradeoff required a decision? + +### Decision +- What was chosen? + +### Why +- Why was this option selected over the alternatives? + +### Follow-Up +- What should the next session verify, document, or revisit? diff --git a/skills/skill-task-continuity/assets/agent-state/root/HANDOFF.template.md b/skills/skill-task-continuity/assets/agent-state/root/HANDOFF.template.md new file mode 100644 index 0000000..2a00410 --- /dev/null +++ b/skills/skill-task-continuity/assets/agent-state/root/HANDOFF.template.md @@ -0,0 +1,25 @@ +# Handoff Summary + +## Task Summary +One paragraph on the active task and why this handoff exists. + +## Current Status +State what is done, what is in progress, and what remains. + +## What Changed In This Session +List the meaningful edits or verified findings from this session only. + +## Hard Constraints To Preserve +Call out non-negotiable requirements, boundaries, or decisions the next session must keep. + +## Files / Modules Of Interest +Name the files, modules, or artifacts the next session should open first. + +## Open Problems +List blockers, unresolved questions, or risks that still need work. + +## Exact Next Action +Write the single next action that should happen first when work resumes. + +## Resume Prompt +Resume this task from the recorded handoff. Continue from the recorded status, preserve the listed constraints, inspect the files of interest, resolve the open problems in priority order, perform the exact next action first, and update the handoff if anything material changes. diff --git a/skills/skill-task-continuity/assets/agent-state/root/PACKET.template.md b/skills/skill-task-continuity/assets/agent-state/root/PACKET.template.md new file mode 100644 index 0000000..5a309ff --- /dev/null +++ b/skills/skill-task-continuity/assets/agent-state/root/PACKET.template.md @@ -0,0 +1,32 @@ +# Context Packet + +## Objective For This Turn +- State the exact action this packet should enable. +- Keep it narrow enough for one owner and one short execution loop. + +## Scope For This Turn +- List what this turn should cover. +- List what should stay out of scope for now. + +## Inputs To Load +- Name the smallest set of files, notes, or commands worth opening first. +- Prefer links and paths over pasted detail. + +## Facts To Preserve +- Record only the verified facts needed for this turn. +- Leave stale or optional detail in longer state files. + +## Constraints To Preserve +- List hard requirements, approvals, and safety limits. +- Separate hard constraints from preferences or guesses. + +## Risks / Open Questions +- Capture blockers, fragile spots, or unknowns that matter right now. +- Drop anything that does not affect the next action. + +## Exit Criteria +- Define what must be true before this packet is considered complete. +- Keep the criteria observable. + +## Next Command / Prompt +- End with the first command, file, or prompt the next agent should use. diff --git a/skills/skill-task-continuity/assets/agent-state/root/RUN_LOG.template.md b/skills/skill-task-continuity/assets/agent-state/root/RUN_LOG.template.md new file mode 100644 index 0000000..3e1f21a --- /dev/null +++ b/skills/skill-task-continuity/assets/agent-state/root/RUN_LOG.template.md @@ -0,0 +1,24 @@ +# Run Log + +Append one entry per meaningful work session. +Capture commands, checks, and notable observations that would save the next session time. + +## Entry Template + +### Session +- Date: +- Owner: +- Goal: + +### Commands / Checks +- List the commands you ran. +- Note pass, fail, or skipped outcomes. + +### Files Touched +- List the files changed or inspected. + +### Notes +- Record noteworthy findings, blockers, or follow-up ideas. + +### Next Session +- State the next action if work resumes from this log entry. diff --git a/skills/skill-task-continuity/assets/agent-state/root/TASK_STATE.template.md b/skills/skill-task-continuity/assets/agent-state/root/TASK_STATE.template.md new file mode 100644 index 0000000..9157bbd --- /dev/null +++ b/skills/skill-task-continuity/assets/agent-state/root/TASK_STATE.template.md @@ -0,0 +1,45 @@ +# Task State + +## Current Objective +- State the active task in one sentence. +- Mark assumptions as assumptions, not facts. + +## Scope / Non-Goals +- List what this refresh covers. +- Call out work that belongs to phase gates or final handoffs elsewhere. + +## Hard Constraints +- Capture fixed requirements, approvals, and safety limits. +- Separate must-follow constraints from preferences. + +## Current Codebase Facts +- Record verified repository facts only. +- Note the source if a fact came from tests, files, or commands. + +## Completed Work +- Summarize what is already done and still valid. +- Keep each item specific enough to avoid rework. + +## Open Issues / Risks +- List blockers, uncertainties, and fragile areas. +- Label each item as a fact, assumption, or risk. + +## Next Recommended Action +- Name the next concrete step for the downstream agent. +- Keep it narrow and immediately actionable. + +## Verification Still Needed +- List tests, checks, or reviews that have not run yet. +- Distinguish missing verification from failed verification. + +## Recent Decisions +- Capture decisions with a short reason. +- Separate decisions from open options. + +## Compression / Archive Notes +- List stale detail that should move out of active root state. +- Point to archive paths or packet updates instead of pasting long history here. + +## Resume Checklist +- Give a short restart checklist in execution order. +- End with the first command, file, or prompt to use next. diff --git a/skills/skill-task-continuity/assets/agent-state/subtasks/HANDOFF.template.md b/skills/skill-task-continuity/assets/agent-state/subtasks/HANDOFF.template.md new file mode 100644 index 0000000..2a00410 --- /dev/null +++ b/skills/skill-task-continuity/assets/agent-state/subtasks/HANDOFF.template.md @@ -0,0 +1,25 @@ +# Handoff Summary + +## Task Summary +One paragraph on the active task and why this handoff exists. + +## Current Status +State what is done, what is in progress, and what remains. + +## What Changed In This Session +List the meaningful edits or verified findings from this session only. + +## Hard Constraints To Preserve +Call out non-negotiable requirements, boundaries, or decisions the next session must keep. + +## Files / Modules Of Interest +Name the files, modules, or artifacts the next session should open first. + +## Open Problems +List blockers, unresolved questions, or risks that still need work. + +## Exact Next Action +Write the single next action that should happen first when work resumes. + +## Resume Prompt +Resume this task from the recorded handoff. Continue from the recorded status, preserve the listed constraints, inspect the files of interest, resolve the open problems in priority order, perform the exact next action first, and update the handoff if anything material changes. diff --git a/skills/skill-task-continuity/assets/agent-state/subtasks/PACKET.template.md b/skills/skill-task-continuity/assets/agent-state/subtasks/PACKET.template.md new file mode 100644 index 0000000..5a309ff --- /dev/null +++ b/skills/skill-task-continuity/assets/agent-state/subtasks/PACKET.template.md @@ -0,0 +1,32 @@ +# Context Packet + +## Objective For This Turn +- State the exact action this packet should enable. +- Keep it narrow enough for one owner and one short execution loop. + +## Scope For This Turn +- List what this turn should cover. +- List what should stay out of scope for now. + +## Inputs To Load +- Name the smallest set of files, notes, or commands worth opening first. +- Prefer links and paths over pasted detail. + +## Facts To Preserve +- Record only the verified facts needed for this turn. +- Leave stale or optional detail in longer state files. + +## Constraints To Preserve +- List hard requirements, approvals, and safety limits. +- Separate hard constraints from preferences or guesses. + +## Risks / Open Questions +- Capture blockers, fragile spots, or unknowns that matter right now. +- Drop anything that does not affect the next action. + +## Exit Criteria +- Define what must be true before this packet is considered complete. +- Keep the criteria observable. + +## Next Command / Prompt +- End with the first command, file, or prompt the next agent should use. diff --git a/skills/skill-task-continuity/assets/agent-state/subtasks/RUN_LOG.template.md b/skills/skill-task-continuity/assets/agent-state/subtasks/RUN_LOG.template.md new file mode 100644 index 0000000..7d1943e --- /dev/null +++ b/skills/skill-task-continuity/assets/agent-state/subtasks/RUN_LOG.template.md @@ -0,0 +1,24 @@ +# Run Log + +Append one entry per meaningful subtask work session. +Capture commands, checks, and notable observations that would save the next session time. + +## Entry Template + +### Session +- Date: +- Owner: +- Goal: + +### Commands / Checks +- List the commands you ran. +- Note pass, fail, or skipped outcomes. + +### Files Touched +- List the files changed or inspected. + +### Notes +- Record noteworthy findings, blockers, or follow-up ideas. + +### Parent Follow-Up +- State what the parent task should absorb after this session. diff --git a/skills/skill-task-continuity/assets/agent-state/subtasks/TASK_STATE.template.md b/skills/skill-task-continuity/assets/agent-state/subtasks/TASK_STATE.template.md new file mode 100644 index 0000000..4595c03 --- /dev/null +++ b/skills/skill-task-continuity/assets/agent-state/subtasks/TASK_STATE.template.md @@ -0,0 +1,40 @@ +# Subtask State + +## Subtask Objective +- State the bounded child task in one sentence. +- Keep it tied to one parent task outcome. + +## Parent Context +- Link back to the parent task or packet. +- Record only the parent facts this subtask must preserve. + +## Local Scope / Non-Goals +- List what this subtask owns. +- Mark adjacent work that stays with the parent task or another subtask. + +## Inputs To Load +- Name the files, commands, and artifacts this subtask needs first. +- Keep the list minimal. + +## Local Facts +- Record verified facts discovered inside this subtask. +- Avoid duplicating unchanged parent state. + +## Open Risks / Blockers +- Capture blockers, unknowns, or fragile areas local to this subtask. +- Escalate cross-cutting risks back to the parent task. + +## Exit Criteria +- List the conditions for closing or merging this subtask. +- Make the criteria observable. + +## Next Recommended Action +- State the next local action. +- Keep it small enough for one short turn. + +## Verification Still Needed +- List checks that remain for this subtask. +- Separate missing verification from failed verification. + +## Merge / Closure Notes +- Record what the parent task should absorb when this subtask finishes. diff --git a/skills/skill-task-continuity/references/composition-guide.md b/skills/skill-task-continuity/references/composition-guide.md index d7a69ad..6723a1e 100644 --- a/skills/skill-task-continuity/references/composition-guide.md +++ b/skills/skill-task-continuity/references/composition-guide.md @@ -1,11 +1,13 @@ # Composition Guide `skill-task-continuity` is the suite entry point for downstream teams that want the long-task continuity workflow to feel coherent without collapsing the atomic package boundaries. -Use it to explain how the pieces fit together and to bootstrap downstream files, not to replace the atomic skills. +Use it to explain how packets, root state, subtasks, gates, and handoffs fit together and to bootstrap downstream files, not to replace the atomic skills. ## How The Suite Fits Together - `skill-context-keeper` refreshes current task state and keeps facts, assumptions, and decisions separated. +- `skill-subtask-context` owns bounded child-task state so subtask reasoning stays isolated from the root task. +- `skill-context-packet` compresses the minimum context needed for the next root or subtask turn. - `skill-phase-gate` adds meaningful preflight or postflight checkpoints around substantial edits. - `skill-handoff-summary` writes the continuation-oriented handoff when work pauses or changes owners. @@ -15,7 +17,7 @@ If the team wants all four packages available immediately, the suite can also be ## 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 +- install the full suite in one command when you want all six 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. @@ -24,10 +26,12 @@ Instead, it documents the existing multi-path `skill-installer` flow so users ca Use the atomic skills with direct prompts like these: -- `Use $skill-context-keeper to refresh .agent-state/TASK_STATE.md before more implementation work.` +- `Use $skill-context-keeper to refresh .agent-state/root/TASK_STATE.md before more implementation work.` +- `Use $skill-subtask-context to open or refresh .agent-state/subtasks/api-migration/TASK_STATE.md for this child task.` +- `Use $skill-context-packet to compress the next turn into .agent-state/root/PACKET.md before we continue.` - `Use $skill-phase-gate for a preflight before this risky multi-file change.` - `Use $skill-phase-gate for a postflight gate now that the refactor is done.` -- `Use $skill-handoff-summary to write .agent-state/HANDOFF.md before we pause.` +- `Use $skill-handoff-summary to write the root or subtask handoff before we pause.` If the request is about the suite itself, start with `skill-task-continuity` and then route into the atomic skill that owns the next action. @@ -36,23 +40,33 @@ If the request is about the suite itself, start with `skill-task-continuity` and ```text AGENTS.md .agent-state/ - TASK_STATE.md - HANDOFF.md - DECISIONS.md - RUN_LOG.md + INDEX.md + root/ + TASK_STATE.md + PACKET.md + HANDOFF.md + DECISIONS.md + RUN_LOG.md + subtasks/ + archive/ + root/ + subtasks/ + packets/ ``` -This layout is intentionally small. -The suite ships templates for these files so the downstream repo can standardize how agents resume work. +Beginner mode is the subset that only uses `INDEX.md` and `root/`. +Expanded mode starts when the repo opens real child-task folders under `subtasks/`. ## Recommended Long-Task Loop -1. Read `.agent-state/TASK_STATE.md` and `.agent-state/HANDOFF.md` before taking over the task. -2. If the next edit is substantial or risky, run a `skill-phase-gate` preflight. -3. Implement the change. -4. Refresh `.agent-state/TASK_STATE.md` with `skill-context-keeper`. -5. Update `.agent-state/DECISIONS.md` or `.agent-state/RUN_LOG.md` if you made a durable choice or ran checks worth preserving. -6. If work stops, refresh `.agent-state/HANDOFF.md` with `skill-handoff-summary`. +1. Read `.agent-state/INDEX.md` first. +2. Start with `.agent-state/root/PACKET.md` or a subtask packet instead of loading full state by default. +3. If the packet is not enough, open the matching root or subtask task-state file. +4. If the next edit is substantial or risky, run a `skill-phase-gate` preflight. +5. Implement the change. +6. Refresh the matching root or subtask state file, then compress the next turn back into a packet. +7. Update the decisions log or run log only when the evidence is worth preserving. +8. If work stops, refresh the root or subtask handoff. ## Optional Repo-Local Wrapper Pattern @@ -60,7 +74,9 @@ Some teams like to add repo-local helper prompts or examples under `.agents/skil That can be useful, but it is optional. Keep wrappers thin and explicit, for example: -- `.agents/skills/refresh-task-state.md` that says to invoke `skill-context-keeper` for `.agent-state/TASK_STATE.md` +- `.agents/skills/refresh-task-state.md` that says to invoke `skill-context-keeper` for `.agent-state/root/TASK_STATE.md` +- `.agents/skills/open-subtask.md` that says to invoke `skill-subtask-context` +- `.agents/skills/compress-next-turn.md` that says to invoke `skill-context-packet` - `.agents/skills/preflight-risky-change.md` that says to invoke `skill-phase-gate` - `.agents/skills/write-handoff.md` that says to invoke `skill-handoff-summary` 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 cc4f4f8..3ab5d6d 100644 --- a/skills/skill-task-continuity/references/composition-guide.zh-CN.md +++ b/skills/skill-task-continuity/references/composition-guide.zh-CN.md @@ -1,11 +1,13 @@ # 组合指南 `skill-task-continuity` 是长任务连续性套件的入口包，方便下游仓库用一个清晰的入口理解整套工作流，同时不打破原子技能包的边界。 -它负责解释这些包如何组合，以及如何为下游仓库引导初始化文件，而不是取代原子技能。 +它负责解释 packet、root state、subtask、gate 和 handoff 如何组合，以及如何为下游仓库引导初始化文件，而不是取代原子技能。 ## 套件如何组合 - `skill-context-keeper` 负责刷新当前任务状态，并清楚区分事实、假设和决策。 +- `skill-subtask-context` 负责维护边界清楚的子任务状态，避免子任务推理污染根任务。 +- `skill-context-packet` 负责把下一轮真正需要的上下文压缩成最小注入对象。 - `skill-phase-gate` 负责在较大或较高风险的改动前后增加紧凑的检查点。 - `skill-handoff-summary` 负责在暂停或交接时写出面向续做的交接摘要。 @@ -15,7 +17,7 @@ ## 安装选择 - 只安装 `skill-task-continuity`，适合先从套件入口理解整体结构 -- 用一条命令安装整套工具链，适合一开始就把 4 个包全部装好 +- 用一条命令安装整套工具链，适合一开始就把 6 个包全部装好 这个组合包本身不会隐式自动安装另外三个原子包。 它做的是把现有的多路径 `skill-installer` 用法文档化，让用户既能一条命令装完整套件，又不会遇到隐藏副作用。 @@ -24,10 +26,12 @@ 可以直接使用下面这类提示词： -- `Use $skill-context-keeper to refresh .agent-state/TASK_STATE.md before more implementation work.` +- `Use $skill-context-keeper to refresh .agent-state/root/TASK_STATE.md before more implementation work.` +- `Use $skill-subtask-context to open or refresh .agent-state/subtasks/api-migration/TASK_STATE.md for this child task.` +- `Use $skill-context-packet to compress the next turn into .agent-state/root/PACKET.md before we continue.` - `Use $skill-phase-gate for a preflight before this risky multi-file change.` - `Use $skill-phase-gate for a postflight gate now that the refactor is done.` -- `Use $skill-handoff-summary to write .agent-state/HANDOFF.md before we pause.` +- `Use $skill-handoff-summary to write the root or subtask handoff before we pause.` 如果需求本身就是在搭建或协调整套连续性流程，则先从 `skill-task-continuity` 开始，再路由到真正拥有下一步动作的原子技能。 @@ -36,23 +40,33 @@ ```text AGENTS.md .agent-state/ - TASK_STATE.md - HANDOFF.md - DECISIONS.md - RUN_LOG.md + INDEX.md + root/ + TASK_STATE.md + PACKET.md + HANDOFF.md + DECISIONS.md + RUN_LOG.md + subtasks/ + archive/ + root/ + subtasks/ + packets/ ``` -这个布局刻意保持精简。 -套件会提供这些文件的模板，帮助下游仓库标准化“如何恢复工作”的约定。 +beginner mode 是只使用 `INDEX.md` 和 `root/` 的子集。 +当仓库真正打开 `subtasks/` 里的子任务目录时，就进入 expanded mode。 ## 推荐的长任务循环 -1. 接手任务前先阅读 `.agent-state/TASK_STATE.md` 和 `.agent-state/HANDOFF.md`。 -2. 如果下一步改动较大或风险较高，先运行一次 `skill-phase-gate` 预检。 -3. 执行实现工作。 -4. 用 `skill-context-keeper` 刷新 `.agent-state/TASK_STATE.md`。 -5. 如果本轮产生了需要长期保留的决策或验证记录，则补充 `.agent-state/DECISIONS.md` 或 `.agent-state/RUN_LOG.md`。 -6. 如果工作要暂停，则用 `skill-handoff-summary` 刷新 `.agent-state/HANDOFF.md`。 +1. 先阅读 `.agent-state/INDEX.md`。 +2. 默认优先加载 `.agent-state/root/PACKET.md` 或某个子任务 packet，而不是一上来就读整份状态。 +3. 只有当 packet 不够时，再打开对应的 root 或 subtask task state。 +4. 如果下一步改动较大或风险较高，先运行一次 `skill-phase-gate` 预检。 +5. 执行实现工作。 +6. 刷新对应的 root 或 subtask state，然后再把下一轮需要的内容压回 packet。 +7. 只有当某些决策或证据值得长期保留时，才补充 decisions log 或 run log。 +8. 如果工作要暂停，则刷新 root 或 subtask handoff。 ## 可选的仓库本地包装模式 @@ -60,7 +74,9 @@ AGENTS.md 这是一种可选模式，不是强制要求。 建议保持这些包装非常薄，例如： -- `.agents/skills/refresh-task-state.md`：提示调用 `skill-context-keeper` 来刷新 `.agent-state/TASK_STATE.md` +- `.agents/skills/refresh-task-state.md`：提示调用 `skill-context-keeper` 来刷新 `.agent-state/root/TASK_STATE.md` +- `.agents/skills/open-subtask.md`：提示调用 `skill-subtask-context` +- `.agents/skills/compress-next-turn.md`：提示调用 `skill-context-packet` - `.agents/skills/preflight-risky-change.md`：提示调用 `skill-phase-gate` - `.agents/skills/write-handoff.md`：提示调用 `skill-handoff-summary` diff --git a/skills/skill-task-continuity/references/install-playbook.md b/skills/skill-task-continuity/references/install-playbook.md index 6536966..a125a54 100644 --- a/skills/skill-task-continuity/references/install-playbook.md +++ b/skills/skill-task-continuity/references/install-playbook.md @@ -9,18 +9,25 @@ It must not be pointed back at the public skill library root. The bootstrap helper copies these templates into the downstream repo: - `AGENTS.md` -- `.agent-state/TASK_STATE.md` -- `.agent-state/HANDOFF.md` -- `.agent-state/DECISIONS.md` -- `.agent-state/RUN_LOG.md` - -`TASK_STATE.md` and `HANDOFF.md` are duplicated from the atomic packages so consumers can bootstrap from one package while the atomic packages remain the source of truth. +- `.agent-state/INDEX.md` +- `.agent-state/root/TASK_STATE.md` +- `.agent-state/root/PACKET.md` +- `.agent-state/root/HANDOFF.md` +- `.agent-state/root/DECISIONS.md` +- `.agent-state/root/RUN_LOG.md` +- `.agent-state/subtasks/` +- `.agent-state/archive/root/` +- `.agent-state/archive/subtasks/` +- `.agent-state/archive/packets/` + +Root `TASK_STATE.md` and `HANDOFF.md` are duplicated from the atomic packages so consumers can bootstrap from one package while the atomic packages remain the source of truth. +The suite also ships packet and subtask templates for later expansion. ## Bootstrap Walkthrough 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 + - the full long-task continuity suite if you want all six packages available immediately 2. Pick the downstream repository root you want to prepare. 3. Ask Codex directly when you want a natural-language bootstrap flow: @@ -47,30 +54,43 @@ python3 skills/skill-task-continuity/scripts/bootstrap_suite.py --target /path/t ## 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`: +If you want all six 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-subtask-context \ + skills/skill-context-packet \ skills/skill-phase-gate \ skills/skill-handoff-summary \ skills/skill-task-continuity ``` -Add `--ref v0.6.1` when you want the pinned release. +Add `--ref ` when you want a pinned release. ## Expected Downstream Layout ```text AGENTS.md .agent-state/ - TASK_STATE.md - HANDOFF.md - DECISIONS.md - RUN_LOG.md + INDEX.md + root/ + TASK_STATE.md + PACKET.md + HANDOFF.md + DECISIONS.md + RUN_LOG.md + subtasks/ + archive/ + root/ + subtasks/ + packets/ ``` +Beginner mode uses `INDEX.md` plus `root/` only. +Expanded mode uses `subtasks/` and `archive/`. The helper creates missing parent directories automatically. Without `--force`, existing files are preserved. @@ -79,9 +99,12 @@ Without `--force`, existing files are preserved. After bootstrapping: 1. Read `AGENTS.md` in the downstream repo. -2. Adjust repo-local wording only if your team needs thin wrappers or examples. -3. Start invoking the atomic skills directly for real work: - - `skill-context-keeper` for state refresh +2. Start with `.agent-state/INDEX.md`, then open `.agent-state/root/PACKET.md`. +3. Adjust repo-local wording only if your team needs thin wrappers or examples. +4. Start invoking the atomic skills directly for real work: + - `skill-context-keeper` for root state refresh + - `skill-subtask-context` for bounded child tasks + - `skill-context-packet` for packet compression - `skill-phase-gate` for meaningful checkpoints - `skill-handoff-summary` for pauses and transfers 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 1fde2d1..2dd99ff 100644 --- a/skills/skill-task-continuity/references/install-playbook.zh-CN.md +++ b/skills/skill-task-continuity/references/install-playbook.zh-CN.md @@ -9,18 +9,25 @@ 启动脚本会把以下模板复制到下游仓库： - `AGENTS.md` -- `.agent-state/TASK_STATE.md` -- `.agent-state/HANDOFF.md` -- `.agent-state/DECISIONS.md` -- `.agent-state/RUN_LOG.md` - -其中 `TASK_STATE.md` 与 `HANDOFF.md` 是从原子包复制过来的重复模板，这样下游仓库可以从一个包完成初始化，而原子包仍然是这些模板的真实来源。 +- `.agent-state/INDEX.md` +- `.agent-state/root/TASK_STATE.md` +- `.agent-state/root/PACKET.md` +- `.agent-state/root/HANDOFF.md` +- `.agent-state/root/DECISIONS.md` +- `.agent-state/root/RUN_LOG.md` +- `.agent-state/subtasks/` +- `.agent-state/archive/root/` +- `.agent-state/archive/subtasks/` +- `.agent-state/archive/packets/` + +其中 root `TASK_STATE.md` 与 `HANDOFF.md` 是从原子包复制过来的重复模板，这样下游仓库可以从一个包完成初始化，而原子包仍然是这些模板的真实来源。 +套件也会同时提供 packet 和 subtask 模板，方便后续扩展。 ## 启动流程 1. 先决定安装方式： - 只安装 `skill-task-continuity`，先拿到套件入口和 bootstrap 能力 - - 一次安装整套连续性工具链，直接把 4 个包都装好 + - 一次安装整套连续性工具链，直接把 6 个包都装好 2. 选定需要初始化的下游仓库根目录。 3. 如果你希望通过自然语言让 Codex 帮你完成初始化，可以直接这样对 Codex 说： @@ -46,31 +53,43 @@ python3 skills/skill-task-continuity/scripts/bootstrap_suite.py --target /path/t ## 一条命令安装整套工具链 -如果你想把 4 个连续性包一次装好，可以直接利用 `skill-installer` 现有的多路径能力： +如果你想把 6 个连续性包一次装好，可以直接利用 `skill-installer` 现有的多路径能力： ```bash python3 /scripts/install-skill-from-github.py \ --repo Golden-Promise/codex-skill-library \ --path \ skills/skill-context-keeper \ + skills/skill-subtask-context \ + skills/skill-context-packet \ skills/skill-phase-gate \ skills/skill-handoff-summary \ skills/skill-task-continuity ``` -如果你需要固定到当前发布版本，再补上 `--ref v0.6.1`。 +如果你需要固定到某个版本或提交，再补上 `--ref `。 ## 期望的下游布局 ```text AGENTS.md .agent-state/ - TASK_STATE.md - HANDOFF.md - DECISIONS.md - RUN_LOG.md + INDEX.md + root/ + TASK_STATE.md + PACKET.md + HANDOFF.md + DECISIONS.md + RUN_LOG.md + subtasks/ + archive/ + root/ + subtasks/ + packets/ ``` +beginner mode 只使用 `INDEX.md` 加 `root/`。 +expanded mode 才会真正进入 `subtasks/` 和 `archive/`。 脚本会自动创建缺失的父目录。 如果不加 `--force`，已有文件会被保留。 @@ -79,9 +98,12 @@ AGENTS.md 完成启动后： 1. 先阅读下游仓库中的 `AGENTS.md`。 -2. 只有当团队确实需要本地辅助提示或示例时，再做轻量调整。 -3. 真正执行工作时，仍然直接调用原子技能： - - `skill-context-keeper`：刷新任务状态 +2. 再从 `.agent-state/INDEX.md` 进入，并优先打开 `.agent-state/root/PACKET.md`。 +3. 只有当团队确实需要本地辅助提示或示例时，再做轻量调整。 +4. 真正执行工作时，仍然直接调用原子技能： + - `skill-context-keeper`：刷新 root 任务状态 + - `skill-subtask-context`：维护边界清楚的子任务 + - `skill-context-packet`：压缩下一轮 packet - `skill-phase-gate`：执行有意义的检查点 - `skill-handoff-summary`：写暂停或交接摘要 diff --git a/skills/skill-task-continuity/scripts/bootstrap_suite.py b/skills/skill-task-continuity/scripts/bootstrap_suite.py index 5b3ffc4..0185a42 100644 --- a/skills/skill-task-continuity/scripts/bootstrap_suite.py +++ b/skills/skill-task-continuity/scripts/bootstrap_suite.py @@ -10,11 +10,19 @@ LIBRARY_ROOT = PACKAGE_ROOT.parents[1] TEMPLATE_MAP = { "AGENTS.md": "assets/AGENTS.repo-template.md", - ".agent-state/TASK_STATE.md": "assets/agent-state/TASK_STATE.template.md", - ".agent-state/HANDOFF.md": "assets/agent-state/HANDOFF.template.md", - ".agent-state/DECISIONS.md": "assets/agent-state/DECISIONS.template.md", - ".agent-state/RUN_LOG.md": "assets/agent-state/RUN_LOG.template.md", + ".agent-state/INDEX.md": "assets/agent-state/INDEX.template.md", + ".agent-state/root/TASK_STATE.md": "assets/agent-state/root/TASK_STATE.template.md", + ".agent-state/root/PACKET.md": "assets/agent-state/root/PACKET.template.md", + ".agent-state/root/HANDOFF.md": "assets/agent-state/root/HANDOFF.template.md", + ".agent-state/root/DECISIONS.md": "assets/agent-state/root/DECISIONS.template.md", + ".agent-state/root/RUN_LOG.md": "assets/agent-state/root/RUN_LOG.template.md", } +STARTER_DIRECTORIES = [ + ".agent-state/subtasks", + ".agent-state/archive/root", + ".agent-state/archive/subtasks", + ".agent-state/archive/packets", +] def parse_args(): @@ -84,16 +92,43 @@ def iter_operations(target, force): for destination_rel, source_rel in TEMPLATE_MAP.items(): source = PACKAGE_ROOT / source_rel destination = target / destination_rel - action = "overwrite" if destination.exists() and force else "skip" if destination.exists() else "create" + action = ( + "overwrite" + if destination.exists() and force + else "skip" + if destination.exists() + else "create" + ) yield action, source, destination +def iter_directory_operations(target): + for destination_rel in STARTER_DIRECTORIES: + destination = target / destination_rel + action = "skip-dir" if destination.exists() else "create-dir" + yield action, destination + + def apply_operations(target, force, dry_run): validate_target(target) + created_directories = 0 created = 0 overwritten = 0 skipped = 0 + for action, destination in iter_directory_operations(target): + if action == "skip-dir": + print(f"[skip-dir] {destination}") + continue + + created_directories += 1 + verb = "would mkdir" if dry_run else "mkdir" + print(f"[create-dir] {verb} {destination}") + if dry_run: + continue + + destination.mkdir(parents=True, exist_ok=True) + for action, source, destination in iter_operations(target, force): if action == "skip": skipped += 1 @@ -114,7 +149,8 @@ def apply_operations(target, force, dry_run): shutil.copyfile(source, destination) print( - f"Summary: {created} create, {overwritten} overwrite, {skipped} skip" + f"Summary: {created_directories} create-dir, {created} create, " + f"{overwritten} overwrite, {skipped} skip" + (" (dry-run)" if dry_run else "") ) diff --git a/skills/skill-task-continuity/tests/test_bootstrap_suite.py b/skills/skill-task-continuity/tests/test_bootstrap_suite.py index e079ecb..2ec2e1f 100644 --- a/skills/skill-task-continuity/tests/test_bootstrap_suite.py +++ b/skills/skill-task-continuity/tests/test_bootstrap_suite.py @@ -11,11 +11,19 @@ REPO_ROOT = ROOT.parents[1] TEMPLATE_MAP = { "AGENTS.md": "assets/AGENTS.repo-template.md", - ".agent-state/TASK_STATE.md": "assets/agent-state/TASK_STATE.template.md", - ".agent-state/HANDOFF.md": "assets/agent-state/HANDOFF.template.md", - ".agent-state/DECISIONS.md": "assets/agent-state/DECISIONS.template.md", - ".agent-state/RUN_LOG.md": "assets/agent-state/RUN_LOG.template.md", + ".agent-state/INDEX.md": "assets/agent-state/INDEX.template.md", + ".agent-state/root/TASK_STATE.md": "assets/agent-state/root/TASK_STATE.template.md", + ".agent-state/root/PACKET.md": "assets/agent-state/root/PACKET.template.md", + ".agent-state/root/HANDOFF.md": "assets/agent-state/root/HANDOFF.template.md", + ".agent-state/root/DECISIONS.md": "assets/agent-state/root/DECISIONS.template.md", + ".agent-state/root/RUN_LOG.md": "assets/agent-state/root/RUN_LOG.template.md", } +STARTER_DIRECTORIES = [ + ".agent-state/subtasks", + ".agent-state/archive/root", + ".agent-state/archive/subtasks", + ".agent-state/archive/packets", +] class BootstrapSuiteTests(unittest.TestCase): @@ -98,6 +106,11 @@ def test_bootstrap_copies_expected_files(self): (target / relative_path).exists(), f"expected downstream file to exist: {relative_path}", ) + for relative_path in STARTER_DIRECTORIES: + self.assertTrue( + (target / relative_path).is_dir(), + f"expected downstream directory to exist: {relative_path}", + ) def test_bootstrap_never_mutates_public_library_root(self): for relative_path in TEMPLATE_MAP: @@ -124,8 +137,8 @@ def test_bootstrap_preserves_existing_files_without_force(self): target = Path(tmpdir) / "consumer-repo" target.mkdir() - existing = target / ".agent-state" / "RUN_LOG.md" - existing.parent.mkdir() + existing = target / ".agent-state" / "root" / "RUN_LOG.md" + existing.parent.mkdir(parents=True, exist_ok=True) existing.write_text("keep me\n", encoding="utf-8") result = self.run_bootstrap(target) @@ -138,8 +151,8 @@ def test_bootstrap_force_overwrites_existing_files(self): target = Path(tmpdir) / "consumer-repo" target.mkdir() - existing = target / ".agent-state" / "RUN_LOG.md" - existing.parent.mkdir() + existing = target / ".agent-state" / "root" / "RUN_LOG.md" + existing.parent.mkdir(parents=True, exist_ok=True) existing.write_text("old value\n", encoding="utf-8") result = self.run_bootstrap(target, "--force") @@ -148,14 +161,17 @@ def test_bootstrap_force_overwrites_existing_files(self): self.assertNotEqual(existing.read_text(encoding="utf-8"), "old value\n") def test_task_state_and_handoff_templates_match_atomic_assets(self): - suite_task_state = ROOT / "assets" / "agent-state" / "TASK_STATE.template.md" + suite_task_state = ROOT / "assets" / "agent-state" / "root" / "TASK_STATE.template.md" atomic_task_state = ( ROOT.parents[0] / "skill-context-keeper" / "assets" / "TASK_STATE.template.md" ) - suite_handoff = ROOT / "assets" / "agent-state" / "HANDOFF.template.md" + suite_handoff = ROOT / "assets" / "agent-state" / "root" / "HANDOFF.template.md" + suite_subtask_handoff = ( + ROOT / "assets" / "agent-state" / "subtasks" / "HANDOFF.template.md" + ) atomic_handoff = ( ROOT.parents[0] / "skill-handoff-summary" @@ -165,6 +181,7 @@ def test_task_state_and_handoff_templates_match_atomic_assets(self): self.assertTrue(suite_task_state.exists()) self.assertTrue(suite_handoff.exists()) + self.assertTrue(suite_subtask_handoff.exists()) self.assertEqual( suite_task_state.read_text(encoding="utf-8"), atomic_task_state.read_text(encoding="utf-8"), @@ -173,6 +190,47 @@ def test_task_state_and_handoff_templates_match_atomic_assets(self): suite_handoff.read_text(encoding="utf-8"), atomic_handoff.read_text(encoding="utf-8"), ) + self.assertEqual( + suite_subtask_handoff.read_text(encoding="utf-8"), + atomic_handoff.read_text(encoding="utf-8"), + ) + + def test_subtask_and_packet_templates_match_atomic_assets(self): + suite_subtask_state = ( + ROOT / "assets" / "agent-state" / "subtasks" / "TASK_STATE.template.md" + ) + atomic_subtask_state = ( + ROOT.parents[0] + / "skill-subtask-context" + / "assets" + / "TASK_STATE.template.md" + ) + suite_root_packet = ROOT / "assets" / "agent-state" / "root" / "PACKET.template.md" + suite_subtask_packet = ( + ROOT / "assets" / "agent-state" / "subtasks" / "PACKET.template.md" + ) + atomic_packet = ( + ROOT.parents[0] + / "skill-context-packet" + / "assets" + / "PACKET.template.md" + ) + + self.assertTrue(suite_subtask_state.exists()) + self.assertTrue(suite_root_packet.exists()) + self.assertTrue(suite_subtask_packet.exists()) + self.assertEqual( + suite_subtask_state.read_text(encoding="utf-8"), + atomic_subtask_state.read_text(encoding="utf-8"), + ) + self.assertEqual( + suite_root_packet.read_text(encoding="utf-8"), + atomic_packet.read_text(encoding="utf-8"), + ) + self.assertEqual( + suite_subtask_packet.read_text(encoding="utf-8"), + atomic_packet.read_text(encoding="utf-8"), + ) if __name__ == "__main__": diff --git a/skills/skill-task-continuity/tests/test_docs_contract.py b/skills/skill-task-continuity/tests/test_docs_contract.py index cc10ece..3e5b43d 100644 --- a/skills/skill-task-continuity/tests/test_docs_contract.py +++ b/skills/skill-task-continuity/tests/test_docs_contract.py @@ -18,12 +18,16 @@ def test_skills_index_includes_quick_continuity_picker(self): self.assertIn("skill-phase-gate", english_text) self.assertIn("skill-handoff-summary", english_text) self.assertIn("skill-task-continuity", english_text) + self.assertIn("skill-subtask-context", english_text) + self.assertIn("skill-context-packet", english_text) self.assertIn("## 选择合适的连续性技能", chinese_text) self.assertIn("skill-context-keeper", chinese_text) self.assertIn("skill-phase-gate", chinese_text) self.assertIn("skill-handoff-summary", chinese_text) self.assertIn("skill-task-continuity", chinese_text) + self.assertIn("skill-subtask-context", chinese_text) + self.assertIn("skill-context-packet", chinese_text) def test_english_readme_mentions_full_suite_install(self): text = (ROOT / "README.md").read_text(encoding="utf-8") @@ -33,11 +37,16 @@ def test_english_readme_mentions_full_suite_install(self): self.assertIn("one command", lowered) for skill_path in [ "skills/skill-context-keeper", + "skills/skill-subtask-context", + "skills/skill-context-packet", "skills/skill-phase-gate", "skills/skill-handoff-summary", "skills/skill-task-continuity", ]: self.assertIn(skill_path, text) + self.assertIn(".agent-state/index.md", lowered) + self.assertIn(".agent-state/root/packet.md", lowered) + self.assertIn("beginner mode", lowered) def test_chinese_readme_mentions_full_suite_install(self): text = (ROOT / "README.zh-CN.md").read_text(encoding="utf-8") @@ -46,11 +55,16 @@ def test_chinese_readme_mentions_full_suite_install(self): self.assertIn("整套", text) for skill_path in [ "skills/skill-context-keeper", + "skills/skill-subtask-context", + "skills/skill-context-packet", "skills/skill-phase-gate", "skills/skill-handoff-summary", "skills/skill-task-continuity", ]: self.assertIn(skill_path, text) + self.assertIn(".agent-state/INDEX.md", text) + self.assertIn(".agent-state/root/PACKET.md", text) + self.assertIn("beginner mode", text.lower()) def test_english_install_playbook_prefers_natural_language_bootstrap(self): text = (ROOT / "references" / "install-playbook.md").read_text(encoding="utf-8") @@ -79,6 +93,7 @@ def test_bilingual_readme_has_beginner_entry_sections(self): "## Start Here In 30 Seconds", "## What Gets Created In Your Repo", "## Fastest Setup", + "## Beginner Mode", "## Which Skill To Use Next", "## Install", "## Related Skills", @@ -89,6 +104,7 @@ def test_bilingual_readme_has_beginner_entry_sections(self): "## 30 秒快速开始", "## 你的仓库里会创建什么", "## 最快的开始方式", + "## Beginner Mode", "## 下一步该用哪个技能", "## 安装", "## 相关技能", @@ -97,8 +113,14 @@ def test_bilingual_readme_has_beginner_entry_sections(self): self.assertIn("Try this first:", english) self.assertIn("Use skill-task-continuity", english) + self.assertIn("skill-subtask-context", english) + self.assertIn("skill-context-packet", english) + self.assertIn("INDEX.md", english) self.assertIn("先这样对 Codex 说：", chinese) self.assertIn("请用 skill-task-continuity", chinese) + self.assertIn("skill-subtask-context", chinese) + self.assertIn("skill-context-packet", chinese) + self.assertIn("INDEX.md", chinese) if __name__ == "__main__":