cc-devflow 4.5.0 → 4.5.1

package/.claude/skills/cc-roadmap/SKILL.md

@@ -1,6 +1,6 @@
 ---
 name: cc-roadmap
-version: 4.3.2
+version: 4.3.4
 description: "Use when defining, resetting, or narrowing project direction, stage order, or backlog priority before a concrete requirement enters the PDCA loop."
 triggers:
   - "帮我定路线图"
@@ -32,6 +32,8 @@ writes:
 entry_gate:
   - "Read current roadmap, backlog, related capability specs, and surrounding repo context before proposing direction."
   - "Confirm this is a project-direction problem, not a single requirement execution problem."
+  - "Classify planning posture and evidence maturity before selecting the route or forcing questions."
+  - "If the ask contains multiple independent subsystems, decompose them into stages and RM candidates before refining any implementation detail."
   - "Do not decompose implementation tasks while the roadmap is still being decided."
 exit_criteria:
   - "The next 1-3 stages are frozen with goal, why now, dependencies, exit signal, kill signal, and non-goals."
@@ -95,12 +97,13 @@ tool_budget:
 | “不知道下一步做什么” | 主线不清 | `wedge-first` |
 | “后面几阶段都会重复碰同一底座” | 底座风险 | `platform-first` |
 | “增长/交付/信任卡住了” | 当前最大瓶颈 | `rescue-first` |
+| “一个目标里塞了多个可独立交付系统” | 边界过宽 | `decompose-first` |
 
 先给一个**默认推荐**，再解释为什么，不要把用户扔进开放式战略讨论。
 
 ## Harness Contract
 
-- Allowed actions: read current strategy files, repo context, and recent reality; compare route shapes; write `devflow/ROADMAP.md`, `devflow/BACKLOG.md`, and the optional `devflow/roadmap-tracking.json` sidecar used by bundled helpers as the shared roadmap/backlog truth source.
+- Allowed actions: read current strategy files, repo context, and recent reality; compare route shapes; decompose independent subsystems into stages and RM candidates; write `devflow/ROADMAP.md`, `devflow/BACKLOG.md`, and the optional `devflow/roadmap-tracking.json` sidecar used by bundled helpers as the shared roadmap/backlog truth source.
 - Forbidden actions: decompose implementation tasks, invent hidden context, or jump into `cc-plan` before the roadmap is approved.
 - Required evidence: every stage and backlog item must point back to explicit repo facts, user constraints, or observed market signals.
 - Reroute rule: once the conversation collapses to one concrete requirement, stop strategic expansion and hand off to `cc-plan`.
@@ -109,8 +112,9 @@ tool_budget:
 
 1. 如果 `devflow/ROADMAP.md` / `devflow/BACKLOG.md` 已存在，先读现状再重写。
 2. 先判断这是“项目方向问题”还是“单 requirement 执行问题”。
-3. 先做一次上下文扫描，不能跳过现有事实直接写愿景。
-4. 方向没被批准前，不准把 roadmap 偷偷下放成实现任务。
+3. 如果输入是多个独立子系统的混合目标，先拆成阶段和 `RM` 候选；不要继续追问某个子系统的实现细节。
+4. 先做一次上下文扫描，不能跳过现有事实直接写愿景。
+5. 方向没被批准前，不准把 roadmap 偷偷下放成实现任务。
 
 ## Context Sweep
 
@@ -122,20 +126,38 @@ tool_budget:
 4. 最近相关提交、当前分支脏状态、正在进行中的 requirement。
 5. 真实 forcing functions：deadline、发布窗口、资源上限、依赖、distribution、adoption / trust / delivery 卡点。
 6. 当前项目最强的现实证据，以及仍然只能靠假设的空白。
+7. Planning posture：startup / internal / hackathon / OSS / research / learning / side-project / infrastructure。
+8. Evidence maturity：idea / has users / paying users / internal sponsor / infra-only / recovery。
+9. 如果是 developer-facing 或 operator-facing 能力，补齐 target developer/operator、time to first value、magic moment、install / run / debug / upgrade 卡点。
 
 先把这些材料压成一个 `Context Snapshot`，再开始追问用户。
 
+## Evidence-Maturity Routing
+
+不要对所有项目套同一组问题。先用 `planning posture` 和 `evidence maturity` 决定追问深度：
+
+| Evidence maturity | 优先追问 | 不要浪费时间在 |
+| --- | --- | --- |
+| idea / pre-product | 真实用户、status quo、最窄 wedge、需求证据 | 远期平台架构细节 |
+| has users | 现有使用路径、失败/绕路场景、保留率或复用信号、下一阶段 wedge | 假想 persona |
+| paying users / internal sponsor | 付费/赞助动机、扩张边界、不可丢的信任信号、组织风险 | 泛泛市场教育 |
+| infra-only | 当前瓶颈、调用方、现有 workaround、复用边界、迁移/回滚约束 | 伪装成用户访谈的问题 |
+| recovery / trust gap | 事故证据、恢复路径、最小可信修复、停止继续扩张的 kill signal | 新功能愿景 |
+
+第一轮回答后必须做 framing check：术语是否具体、用户是否可命名、痛点是否有行为证据、status quo 是否真实、需求是否只是兴趣。发现答案虚，要先收紧问题，再谈路线。
+
 ## Session Protocol
 
 1. 先探索上下文，不靠默认上下文注入替代阅读。
 2. 先问现实，不先写愿景。
 3. 一次只推进一个关键未知点，不要一口气抛一串问题。
-4. 先写 `Context Snapshot`、证据、约束、非目标，再讨论阶段。
+4. 先写 `Context Snapshot`、planning posture、evidence maturity、证据、约束、非目标，再讨论阶段。
 5. 给出 2-3 种路线图形状，再明确推荐一种，并说明为什么其他路线现在不值得打。
-6. 只冻结 1-3 个阶段。每个阶段都必须有 goal、why now、dependencies、exit signal、kill signal、non-goals。
-7. 把 `RM` 之间的硬依赖压成显式 dependency graph，并标出 parallel-ready wave；不要把“最好按这个顺序做”伪装成 blocker。
-8. backlog 只保留会真的进入下一轮 `cc-plan` 的事项，每项都要带成功信号、下一决策、`Primary Capability`、`Secondary Capabilities`、`Expected Spec Delta`、`Depends On` 与 `Parallel With`。
-9. 用户没批准，不进入 `cc-plan`。
+6. 如果一个方向里有多个可独立交付的子系统，先写清 decomposition：哪些合并为同一阶段，哪些拆成独立 `RM`，为什么。
+7. 只冻结 1-3 个阶段。每个阶段都必须有 goal、why now、dependencies、exit signal、kill signal、non-goals。
+8. 把 `RM` 之间的硬依赖压成显式 dependency graph，并标出 parallel-ready wave；不要把“最好按这个顺序做”伪装成 blocker。
+9. backlog 只保留会真的进入下一轮 `cc-plan` 的事项，每项都要带成功信号、下一决策、`Primary Capability`、`Secondary Capabilities`、`Expected Spec Delta`、`Depends On` 与 `Parallel With`。
+10. 用户没批准，不进入 `cc-plan`。
 
 ## Route Selection Rule
 
@@ -173,14 +195,24 @@ tool_budget:
 8. 当前最大的 adoption、trust、delivery 卡点是什么
 9. 这个 roadmap 成功与失败各自用什么信号判断
 
+如果这是 developer-facing / operator-facing roadmap，再补 4 件事：
+
+10. 目标开发者 / 操作者是谁
+11. 从第一次接触到第一次成功输出需要多久
+12. 让他们觉得“这东西真的有用”的 magic moment 是什么
+13. install / run / debug / upgrade / handoff 中哪个环节最可能让 adoption 失败
+
 ## Approval Gates
 
 1. 没有 `Context Snapshot`，不准给路线推荐。
-2. 没有 2-3 条路线对比，不准直接拍脑袋定主线。
-3. 没有 exit signal / kill signal / non-goals，不算阶段冻结。
-4. 没有明确成功信号和下一决策，不准把事项放进 `Ready For Req-Plan`。
-5. 没有 `RM dependency graph` 或 parallel-ready wave，不准宣称事项可以并发推进。
-6. 没有用户批准，不准把 roadmap item 下放到 `cc-plan`。
+2. 没有 planning posture、evidence maturity 和 framing check，不准给路线推荐。
+3. 没有 2-3 条路线对比，不准直接拍脑袋定主线。
+4. 没有 exit signal / kill signal / non-goals，不算阶段冻结。
+5. 没有明确成功信号和下一决策，不准把事项放进 `Ready For Req-Plan`。
+6. developer-facing / operator-facing item 没有 target user、time to first value 或 adoption bottleneck，不准标成 ready。
+7. 没有 `RM dependency graph` 或 parallel-ready wave，不准宣称事项可以并发推进。
+8. 没有独立子系统拆分判断，不准把大而混杂的方向伪装成单一主线。
+9. 没有用户批准，不准把 roadmap item 下放到 `cc-plan`。
 
 ## Review Loop
 
@@ -192,7 +224,10 @@ tool_budget:
 4. Feasibility scan：阶段目标与团队容量、依赖、distribution 约束是否接得上。
 5. Graph scan：`Depends On` 是否只包含硬阻塞，图里有没有环，parallel-ready wave 是否真的共享同一前置。
 6. Spec scan：每个 roadmap item 是否都落到某个 capability，而不是悬空需求。
-7. Handoff scan：第一批 roadmap item 是否已经自然长成可进入 `cc-plan` 的对象。
+7. Decomposition scan：多个独立子系统是否已拆成阶段 / `RM` 候选，而不是塞进一个含糊阶段。
+8. Handoff scan：第一批 roadmap item 是否已经自然长成可进入 `cc-plan` 的对象。
+9. Evidence maturity scan：问题路由是否匹配 idea / user / paying / infra / recovery 状态，还是拿同一套问题硬套所有项目。
+10. Adoption scan：developer-facing / operator-facing item 是否写清目标人、time to first value、magic moment 和 adoption bottleneck。
 
 ## Output
 

package/.claude/skills/cc-roadmap/assets/BACKLOG_TEMPLATE.md

@@ -19,8 +19,18 @@
 
 - Serial spine:
 - Parallel-ready next wave:
+- Decomposition notes:
 - Notes on blockers:
 
+## Adoption Handoff
+
+- Planning posture:
+- Evidence maturity:
+- Target developer / operator:
+- Time to first value:
+- Magic moment:
+- Adoption bottleneck:
+
 ## Ready For Req-Plan
 
 - RM-001:
@@ -33,6 +43,11 @@
   - Expected spec delta:
   - Open risks:
   - First planning question:
+  - Evidence maturity:
+  - Target developer / operator:
+  - Time to first value:
+  - Magic moment:
+  - Adoption bottleneck:
   - Required context to load:
   - Depends On:
   - Parallel With:

package/.claude/skills/cc-roadmap/assets/ROADMAP_TEMPLATE.md

@@ -15,17 +15,24 @@
 ## Context Snapshot
 
 - Product / repo:
+- Planning posture:
 - Project stage:
+- Evidence maturity:
 - Users:
 - Pain:
 - Existing workaround:
 - Strongest demand evidence:
+- Framing check:
 - Why now:
 - Distribution path:
 - Deadline / forcing function:
 - Team / capacity:
 - Hard constraints:
 - Adoption / trust bottleneck:
+- Target developer / operator:
+- Time to first value:
+- Magic moment:
+- Install / run / debug / upgrade bottleneck:
 - Known unknowns:
 - Relevant capabilities:
 
@@ -45,6 +52,7 @@
 | wedge-first |  |  | Recommended / Rejected |
 | platform-first |  |  | Rejected |
 | rescue-first |  |  | Rejected |
+| decompose-first |  |  | Recommended / Rejected |
 
 ## Recommended Route
 
@@ -64,6 +72,33 @@
 - What we refuse to build yet:
 - 6-12 month pull:
 
+## Evidence-Maturity Routing
+
+- Planning posture:
+- Evidence maturity:
+- Questions selected:
+- Questions intentionally skipped:
+- Reason this route matches maturity:
+- Evidence that would change the route:
+
+## DX / Operator Adoption Context
+
+- Applies: Yes / No
+- Target developer / operator:
+- Current first-success path:
+- Target time to first value:
+- Magic moment:
+- Install / run / debug / upgrade risks:
+- Adoption bottleneck:
+
+## Subsystem Decomposition
+
+| Subsystem / RM candidate | User value | Can ship independently? | Merge / split decision | Reason |
+|--------------------------|------------|-------------------------|------------------------|--------|
+| RM-001 |  | Yes / No | Merge / Split |  |
+
+> 如果一个目标里塞了多个独立子系统，先拆阶段和 `RM`，再谈优先级。不要把大杂烩写成一个阶段。
+
 ## Stage Overview
 
 | Stage | Goal | Why now | Primary capabilities | Dependencies | Exit signal | Kill signal | Non-goals |
@@ -140,6 +175,8 @@ flowchart LR
 
 - Rejected path A:
 - Rejected path B:
+- Rejected maturity route:
+- Developer / operator adoption assumptions:
 - Open assumptions to verify next:
 - What changed in this version:
 

package/.claude/skills/cc-roadmap/assets/TRACKING_TEMPLATE.json

@@ -6,12 +6,13 @@
   "lastSyncedAt": "2026-04-19",
   "backlogMeta": {
     "roadmapVersion": "roadmap.v1",
-    "skillVersion": "4.3.2",
+    "skillVersion": "4.3.4",
     "currentFocusStage": "Stage 1"
   },
   "dependencyHandoff": {
     "serialSpine": "RM-001",
     "parallelReadyNextWave": "-",
+    "decompositionNotes": "-",
     "notesOnBlockers": "-"
   },
   "items": [

package/CHANGELOG.md

@@ -9,6 +9,26 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [4.5.1] - 2026-04-28
+
+### Planning Evidence Gates
+
+v4.5.1 strengthens roadmap and requirement planning so downstream execution gets
+clearer evidence, option tradeoffs, rescue behavior, and test obligations before
+implementation starts.
+
+### Changed
+
+- Updated `cc-roadmap` to record planning posture, evidence maturity, framing checks, and developer/operator adoption handoff fields.
+- Updated `cc-plan` to require named option roles, implementation decision horizon, error/rescue mapping, test framework evidence, coverage quality mapping, and regression-test planning.
+- Updated README and getting-started docs to describe the new roadmap and planning quality gates.
+- Refreshed public examples and skill binding metadata for `cc-roadmap@4.3.4` and `cc-plan@3.5.6`.
+
+### Fixed
+
+- Improved publish validation diagnostics for YAML frontmatter list items that accidentally parse as mappings when they contain `": "`.
+- Added a regression test so malformed public-skill string arrays report the exact field, index, actual type, and repair hint.
+
 ## [4.5.0] - 2026-04-27
 
 ### ✨ Runtime YAML Config

package/CODE_OF_CONDUCT.md

@@ -0,0 +1,39 @@
+# Code of Conduct
+
+[中文版](./CODE_OF_CONDUCT.zh-CN.md) | [English](./CODE_OF_CONDUCT.md)
+
+## Purpose
+
+cc-devflow is built for practical agent-coding workflows. The project benefits from direct technical debate, but that debate must stay focused on code, design, evidence, and maintainability.
+
+This code of conduct applies to project spaces, including issues, pull requests, discussions, documentation, examples, and maintainer communication channels.
+
+## Expected Behavior
+
+- Be clear, specific, and evidence-based when reporting bugs or reviewing code.
+- Critique ideas, code, architecture, and tradeoffs instead of attacking people.
+- Assume contributors may have different language backgrounds and levels of context.
+- Keep discussions aligned with the project scope: workflow skills, CLI distribution, adapters, examples, and documentation.
+- Respect maintainer decisions after a direction is explained.
+
+## Unacceptable Behavior
+
+- Harassment, threats, insults, or discriminatory language.
+- Personal attacks, repeated bad-faith arguments, or derailing technical threads.
+- Publishing private information without permission.
+- Spam, advertising, or automated low-quality issue and PR noise.
+- Security disclosure pressure, public exploit details, or demands for private maintainer information.
+
+## Reporting
+
+For conduct concerns, open a private maintainer contact path if one is available in the project profile. If no private path exists, create a GitHub issue with only the minimum public context needed and ask maintainers to move the discussion to a private channel.
+
+For vulnerabilities, do not use conduct reports. Follow [SECURITY.md](./SECURITY.md).
+
+## Enforcement
+
+Maintainers may remove content, close issues or pull requests, block accounts, or limit participation when behavior harms the project. Enforcement should be proportional, evidence-based, and focused on restoring a productive project environment.
+
+## Notes
+
+This is a project-specific conduct policy, written to match cc-devflow's technical collaboration model. It is intentionally short so contributors can read and apply it quickly.

package/CODE_OF_CONDUCT.zh-CN.md

@@ -0,0 +1,39 @@
+# 行为准则
+
+[中文版](./CODE_OF_CONDUCT.zh-CN.md) | [English](./CODE_OF_CONDUCT.md)
+
+## 目的
+
+cc-devflow 服务于真实的 Agent 编程工作流。项目欢迎直接、严格的技术讨论，但讨论必须始终围绕代码、设计、证据和可维护性。
+
+本行为准则适用于项目空间，包括 issue、pull request、discussion、文档、样例，以及维护者沟通渠道。
+
+## 期望行为
+
+- 报告 Bug 或 Review 代码时，保持清晰、具体、基于证据。
+- 批评想法、代码、架构和取舍，不攻击个人。
+- 尊重贡献者的语言背景和上下文差异。
+- 讨论保持在项目范围内：workflow skill、CLI 分发、adapter、样例和文档。
+- 当维护者解释方向后，尊重最终维护决策。
+
+## 不可接受行为
+
+- 骚扰、威胁、侮辱或歧视性表达。
+- 人身攻击、反复恶意争论，或故意带偏技术讨论。
+- 未经许可公开他人隐私信息。
+- 垃圾信息、广告，或自动化低质量 issue / PR 噪音。
+- 安全披露施压、公开漏洞利用细节，或索要维护者私人信息。
+
+## 报告方式
+
+如果遇到行为准则问题，优先使用项目资料中可用的私密维护者联系方式。如果暂时没有私密渠道，可以创建 GitHub issue，只写最少必要的公开上下文，并请求维护者转入私密渠道处理。
+
+漏洞报告不要走行为准则渠道。请遵循 [SECURITY.zh-CN.md](./SECURITY.zh-CN.md)。
+
+## 执行
+
+当行为损害项目环境时，维护者可以删除内容、关闭 issue 或 PR、阻止账号，或限制参与。执行应基于证据、保持比例，并以恢复健康的项目协作为目标。
+
+## 说明
+
+这是为 cc-devflow 技术协作方式定制的项目级行为准则。它刻意保持简短，方便贡献者快速阅读和执行。

package/CONTRIBUTING.md

@@ -0,0 +1,195 @@
+# Contributing to cc-devflow
+
+[中文版](./CONTRIBUTING.zh-CN.md) | [English](./CONTRIBUTING.md)
+
+---
+
+Please also read the [Code of Conduct](./CODE_OF_CONDUCT.md). If you are reporting a vulnerability, follow the [Security Policy](./SECURITY.md) instead of opening a public issue.
+
+## Overview
+
+cc-devflow is now a skills-first repository with a restored distributable CLI.
+
+Public surface:
+
+- `cc-roadmap`
+- `cc-plan`
+- `cc-investigate`
+- `cc-do`
+- `cc-check`
+- `cc-act`
+- `cc-devflow init`
+- `cc-devflow adapt`
+
+Shared runtime helpers may still live under `lib/skill-runtime/`, but they are not the user-facing workflow anymore.
+
+Maintenance helpers may also exist under `.claude/skills/`, such as `cc-spec-init`, `cc-simplify`, and `docs-sync`, but they do not change the public `cc-roadmap + PDCA/IDCA` workflow story.
+
+---
+
+## Development Setup
+
+### Prerequisites
+
+- Node.js 18+
+- npm
+- Git
+
+### Install
+
+```bash
+git clone https://github.com/YOUR_USERNAME/cc-devflow.git
+cd cc-devflow
+npm install
+```
+
+### Local CLI Smoke Test
+
+When working from source, use the repo-local entrypoint:
+
+```bash
+node bin/cc-devflow-cli.js --help
+tmpdir=$(mktemp -d)
+node bin/cc-devflow-cli.js init --dir "$tmpdir"
+node bin/cc-devflow-cli.js adapt --cwd "$tmpdir" --platform codex
+rm -rf "$tmpdir"
+```
+
+For packaged behavior, validate with:
+
+```bash
+npm pack
+node scripts/validate-publish.js
+```
+
+---
+
+## Project Structure
+
+```text
+cc-devflow/
+├── .claude/skills/            # Distributed skills
+├── bin/                       # CLI entrypoints
+├── config/                    # Adapter configuration
+├── docs/                      # Public docs
+├── lib/adapters/              # Platform adapter layer
+├── lib/compiler/              # Multi-platform compiler
+├── lib/skill-runtime/         # Shared runtime helpers and colocated tests for skill scripts
+├── README.md
+├── README.zh-CN.md
+└── package.json
+```
+
+### Contribution Areas
+
+- `.claude/skills/`: skill behavior, assets, references, scripts
+- `bin/`: distributable CLI behavior
+- `lib/compiler/`: skills/prompts parsing, transformation, emitters, rules generation
+- `lib/adapters/`: platform adapter config and validation
+- `lib/skill-runtime/`: shared runtime helpers used by skill-local scripts
+- `docs/`: user-facing documentation
+
+---
+
+## Contribution Rules
+
+### 1. Keep The Public Surface Small
+
+Do not reintroduce old `/flow:*` or `harness:*` CLI instructions into new user docs.
+
+The user-facing story should stay:
+
+- whole pack: `cc-devflow init`
+- platform outputs: `cc-devflow adapt`
+- workflow execution: visible `cc-roadmap + PDCA/IDCA` skills
+- capability truth maintenance: `cc-spec-init`
+
+### 2. Preserve Skills-First Layout
+
+Each shipped skill should keep its own folder:
+
+```text
+.claude/skills/<skill>/
+├── SKILL.md
+├── PLAYBOOK.md
+├── assets/
+├── references/
+└── scripts/
+```
+
+If you touch a shipped skill, treat these files as one contract:
+
+- `SKILL.md`
+- local `CHANGELOG.md`
+- any referenced `PLAYBOOK.md`, `assets/`, `references/`, `scripts/`
+
+Do not change one part of the contract and leave the others stale.
+
+### 3. Keep Distribution Clean
+
+Do not ship transient files in templates or tarballs.
+
+Examples of junk we should exclude:
+
+- `.claude/tsc-cache/`
+- `.DS_Store`
+- local editor or OS artifacts
+
+### 4. Keep Runtime Helpers Secondary
+
+If you touch `lib/skill-runtime/`, keep the behavior testable, but do not document it as the primary user entry. The public workflow still belongs to the shipped skills.
+
+---
+
+## Testing
+
+### Main Test Command
+
+```bash
+npm test
+```
+
+### Focused CLI Regression
+
+```bash
+npm test -- --runInBand lib/skill-runtime/__tests__/cli-bootstrap.integration.test.js
+```
+
+### Publish Validation
+
+```bash
+node scripts/validate-publish.js
+```
+
+This should confirm:
+
+- the expected CLI files exist
+- the expected skills exist
+- the packed tarball is clean
+- transient cache files are not shipped
+
+---
+
+## Documentation Rules
+
+- README and getting-started docs should default to packaged CLI usage
+- contributor-only docs may use `node bin/cc-devflow-cli.js ...`
+- `skills.sh` should be documented only as a single-skill distribution path
+- do not describe `.claude/commands/` as required structure
+- do not describe internal runtime helpers as the supported public workflow
+- if a shipped skill changes, update that skill's `version`, local `CHANGELOG.md`, and affected public docs in the same PR
+- keep the workflow story as `cc-roadmap + PDCA/IDCA` visible skills; document maintenance helpers such as `cc-spec-init` / `cc-simplify` separately
+
+---
+
+## Pull Requests
+
+Good PRs for this repo usually do one of these cleanly:
+
+- improve a skill
+- fix CLI distribution
+- fix compiler/adaptation behavior
+- clean stale docs
+- add focused regression coverage
+
+If a change touches the public surface, update the relevant docs in the same PR.