From a05ec95312f281ac2b5bac9bb6b4031e2cb10c01 Mon Sep 17 00:00:00 2001 From: dafang Date: Fri, 31 Jul 2026 09:51:06 +0800 Subject: [PATCH] feat(skills): type-prefixed work documents and epic sub-design linking MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Dogfood feedback: work/ entries like paseo-native-session-bridge.md give no clue whether they are a feature, issue, or epic when it is time to compress them. Two rules, zero new mechanism: - work docs are named with a type prefix (feat-/issue-/refactor-/epic-), so ls classifies and wrap-up knows the destination per type - epic sub-designs are inline-first: a few lines under the item entry; only risk-escalated items get their own work/feat-{slug}.md, carrying 'epic: {slug}' frontmatter with a backlink from the epic item row — flat files with two-way pointers, no subdirectories. Epic wrap-up now also sweeps its sub-item work docs. Docs (WORKFLOW/README zh+en) synced. 96 passed. Co-Authored-By: Claude Fable 5 --- README.en.md | 2 +- README.md | 2 +- WORKFLOW.en.md | 2 +- WORKFLOW.md | 2 +- plugins/codestable/skills/cs-epic/SKILL.md | 9 +++++---- plugins/codestable/skills/cs-feat/SKILL.md | 6 +++--- plugins/codestable/skills/cs-issue/SKILL.md | 2 +- plugins/codestable/skills/cs-refactor/SKILL.md | 2 +- 8 files changed, 14 insertions(+), 13 deletions(-) diff --git a/README.en.md b/README.en.md index 4075432..27c9ad6 100644 --- a/README.en.md +++ b/README.en.md @@ -158,7 +158,7 @@ CodeStable models real coding work as a set of **entities** and **flows**. |------|--------| | **attention** | A small set of project facts needed every session, kept to at most 25 entries | | **lessons** | One file per pitfall, technique, or research result, retrieved by keyword when relevant | -| **work** | Active cross-session or multi-agent work; ordinary tasks create none, completed work is removed | +| **work** | Active cross-session or multi-agent work, filenames carry a type prefix feat-/issue-/refactor-/epic-; ordinary tasks create none, completed work is removed | | **Project docs / ADRs** | The canonical owner for requirements, domain models, public contracts, and long-lived decisions | ### Flows diff --git a/README.md b/README.md index 3a4a679..19ba517 100644 --- a/README.md +++ b/README.md @@ -161,7 +161,7 @@ CodeStable 顺着软件编码的真实流程来设计，把开发活动建模成 |------|--------| | **attention** | 每次会话都要知道的少量项目事实，保持在 25 条以内 | | **lessons** | 一条一文件的踩坑、技巧和调研结论，靠关键词检索后按需加载 | -| **work** | 跨会话或多人交接的活动任务；普通任务不创建，完成后清理 | +| **work** | 跨会话或多人交接的活动任务，文件名带类型前缀 feat-/issue-/refactor-/epic-；普通任务不创建，完成后清理 | | **项目文档 / ADR** | 需求、领域模型、公开契约与长期技术决策的 canonical owner | ### 流程 diff --git a/WORKFLOW.en.md b/WORKFLOW.en.md index 6237bd1..dbbd414 100644 --- a/WORKFLOW.en.md +++ b/WORKFLOW.en.md @@ -40,7 +40,7 @@ a durable record; remove it when complete unless the owner asks to retain it. .codestable/ ├── attention.md # a small set of facts needed every session, at most 25 entries ├── lessons/ # one Markdown file per reusable lesson, searched by keyword -└── work/ # active cross-session work, removed on completion +└── work/ # active cross-session work, filenames carry a type prefix feat-/issue-/refactor-/epic-, removed on completion ``` Skill-specific context and helpers belong to the owning skill's `references/` and `scripts/`. diff --git a/WORKFLOW.md b/WORKFLOW.md index fdb9031..60ecfad 100644 --- a/WORKFLOW.md +++ b/WORKFLOW.md @@ -35,7 +35,7 @@ bug / 行为异常 -> cs-issue ----------> cs-review（高风险或按需） .codestable/ ├── attention.md # 每次会话需要的少量项目事实，最多 25 条 ├── lessons/ # 一条经验一个 Markdown 文件，按关键词检索 -└── work/ # 活动中的跨会话任务，完成即清 +└── work/ # 活动中的跨会话任务，文件名带类型前缀 feat-/issue-/refactor-/epic-，完成即清 ``` skill 专属 context 与 helper 分别由 owning skill 的 `references/` 和 `scripts/` 提供。项目 diff --git a/plugins/codestable/skills/cs-epic/SKILL.md b/plugins/codestable/skills/cs-epic/SKILL.md index 419b6a6..6346853 100644 --- a/plugins/codestable/skills/cs-epic/SKILL.md +++ b/plugins/codestable/skills/cs-epic/SKILL.md @@ -16,18 +16,19 @@ argument-hint: "[大需求描述]" ## Epic 文档 -epic 天然跨会话，全程维护一个 `.codestable/work/{slug}-epic.md`： +epic 天然跨会话，全程维护一个 `.codestable/work/epic-{slug}.md`（work 文档一律带类型前缀）： ```markdown # {epic 名} 目标 / 边界与取舍 / 验收标准 ## 子项 -- [ ] {子项一句话}（类型：feat/issue/refactor；依赖；验收要点） +- [ ] {子项一句话}（类型：feat/issue/refactor；依赖；验收要点；设计要点就写在此条目下） +- [ ] {高风险子项} → 设计独立落盘 [work/feat-{slug}.md](feat-{slug}.md) - [x] {已完成子项} → 结果一句话 ``` -需要正式 requirement 文档时沿用项目已有位置（如 `.codestable/requirements/`），epic 文档里放指针，不复制两份。 +子项设计**就近优先**：默认写在子项条目下（几行要点即可）；只有触发风险升级信号的子项才独立落 `work/feat-{slug}.md`，其 frontmatter 标 `epic: {epic-slug}`，子项行回链——双向指针，平铺不建子目录。需要正式 requirement 文档时沿用项目已有位置（如 `.codestable/requirements/`），epic 文档里放指针，不复制两份。 ## 硬门槛 @@ -37,5 +38,5 @@ epic 天然跨会话，全程维护一个 `.codestable/work/{slug}-epic.md`： ## 收尾 -- 验收通过后压缩收尾：稳定结论进项目文档 / requirements，经验进 lessons，然后删除 epic work 文档（用户要求留档则保留）。 +- 验收通过后压缩收尾：稳定结论进项目文档 / requirements，经验进 lessons，然后删除 epic work 文档**及其全部子项 work 文档**（按 frontmatter `epic:` 归属收拢；用户要求留档则保留）。 - 本轮若踩坑或被纠偏，推荐用 cs-keep 沉淀一条；用户拒绝即跳过。 diff --git a/plugins/codestable/skills/cs-feat/SKILL.md b/plugins/codestable/skills/cs-feat/SKILL.md index 2915c4c..44b9ae1 100644 --- a/plugins/codestable/skills/cs-feat/SKILL.md +++ b/plugins/codestable/skills/cs-feat/SKILL.md @@ -21,7 +21,7 @@ argument-hint: "[功能描述]" ## 风险升级信号 -出现任何一条，走设计对齐再动手：把方案要点（改什么、契约变化、取舍、影响面——影响面分**必须修改 / 需要验证 / 仍待调查**三层）写入 `.codestable/work/{slug}.md` → 用 `cs-review` 的 design review 做独立审查（修复-复审最多 3 轮，超限连分歧一起上交）→ 交用户确认后动手。存在会卡死方案的技术风险时，先按风险降序垂直打通主路径再铺开（穿刺协议见 `references/code-design.md`）。信号清单： +出现任何一条，走设计对齐再动手：把方案要点（改什么、契约变化、取舍、影响面——影响面分**必须修改 / 需要验证 / 仍待调查**三层）写入 `.codestable/work/feat-{slug}.md` → 用 `cs-review` 的 design review 做独立审查（修复-复审最多 3 轮，超限连分歧一起上交）→ 交用户确认后动手。存在会卡死方案的技术风险时，先按风险降序垂直打通主路径再铺开（穿刺协议见 `references/code-design.md`）。信号清单： - 公开 interface、持久化 schema 或跨模块协议变化； - 权限、信息安全、数据迁移、并发或不可恢复副作用； @@ -39,6 +39,6 @@ argument-hint: "[功能描述]" ## 收尾 - 报告：做了什么、改动文件、验证结果、遗留事项。 -- 高风险任务的 work 文档在设计对齐时已建立；其余任务需要跨会话继续、多人交接或用户要求留痕时补建 `.codestable/work/{slug}.md`。work 文档含目标 / 现场 / 边界 / 证据 / 验收 / 状态与未决六节，随进展更新（"状态与未决"记录进度与待用户确认项，供跨会话恢复）；完成后压缩要点进项目文档或 lessons 并删除，用户要求留档则保留。 -- 属于某个 epic 的子功能时，完成后回报 `cs-epic` 更新其 items 状态。 +- 高风险任务的 work 文档在设计对齐时已建立；其余任务需要跨会话继续、多人交接或用户要求留痕时补建 `.codestable/work/feat-{slug}.md`（work 文档一律带类型前缀 feat- / issue- / refactor- / epic-，整理时按前缀分流去向）。work 文档含目标 / 现场 / 边界 / 证据 / 验收 / 状态与未决六节，随进展更新（"状态与未决"记录进度与待用户确认项，供跨会话恢复）；完成后压缩要点进项目文档或 lessons 并删除，用户要求留档则保留。 +- 属于某个 epic 的子功能时：work 文档 frontmatter 标 `epic: {epic-slug}` 并在 epic 文档的子项行回链；完成后回报 `cs-epic` 更新其子项状态。 - 本轮若踩坑或被纠偏，推荐用 cs-keep 沉淀一条；用户拒绝即跳过。 diff --git a/plugins/codestable/skills/cs-issue/SKILL.md b/plugins/codestable/skills/cs-issue/SKILL.md index 01d78b3..b54f0f7 100644 --- a/plugins/codestable/skills/cs-issue/SKILL.md +++ b/plugins/codestable/skills/cs-issue/SKILL.md @@ -30,5 +30,5 @@ argument-hint: "[问题描述]" - 修复完成后默认用 `cs-review` 做独立审查，仅单行级微小修复可说明后跳过。 - 报告：根因一句话、改动文件、验证结果。 -- 需要跨会话继续时写 `.codestable/work/{slug}.md`（目标 / 现场 / 边界 / 证据 / 验收 / 状态与未决六节）。 +- 需要跨会话继续时写 `.codestable/work/issue-{slug}.md`（目标 / 现场 / 边界 / 证据 / 验收 / 状态与未决六节；work 文档一律带类型前缀）。 - 本轮若踩了新坑或被用户纠偏，推荐用 cs-keep 沉淀一条；用户拒绝即跳过。 diff --git a/plugins/codestable/skills/cs-refactor/SKILL.md b/plugins/codestable/skills/cs-refactor/SKILL.md index cbe0633..cef4adf 100644 --- a/plugins/codestable/skills/cs-refactor/SKILL.md +++ b/plugins/codestable/skills/cs-refactor/SKILL.md @@ -28,5 +28,5 @@ argument-hint: "[重构目标]" ## 收尾 - 报告：改了什么结构、等价性证据（验证输出）、遗留事项。 -- 需要跨会话继续时写 `.codestable/work/{slug}.md`（目标 / 现场 / 边界 / 证据 / 验收 / 状态与未决六节）。 +- 需要跨会话继续时写 `.codestable/work/refactor-{slug}.md`（目标 / 现场 / 边界 / 证据 / 验收 / 状态与未决六节；work 文档一律带类型前缀）。 - 本轮若踩坑或被纠偏，推荐用 cs-keep 沉淀一条；用户拒绝即跳过。