cc-devflow 4.5.0 → 4.5.2

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

@@ -1,55 +1,275 @@
 ---
 name: cc-simplify
-version: 1.1.0
-description: Review changed code for reuse, quality, efficiency, and spec drift, then fix any issues found or flag the drift for the user.
+version: 1.3.0
+description: "Use when changed code needs a Codex-native simplification pass for scope drift, reuse, code quality, efficiency, test quality, and confidence-gated smell fixes before cc-check or cc-act."
 ---
-Simplify: Code Review and Cleanup
 
-Review all changed files for reuse, quality, and efficiency. Fix any issues found.
+# CC-Simplify
 
-## Phase 1: Identify Changes
+`cc-simplify` 是 ship 前的坏味道清理关口。
 
-Run \`git diff\` (or \`git diff HEAD\` if there are staged changes) to see what changed. If there are no git changes, review the most recently modified files that the user mentioned or that you edited earlier in this conversation.
+它不是“顺手重构”。它只做一件事：基于当前 diff 找到已经存在的重复、过度设计、低效路径、测试假象、spec drift，并修掉已经确认的坏味道。
 
-## Phase 2: Launch Three Review Agents in Parallel
+## Iron Law
 
-Use the ${AGENT_TOOL_NAME} tool to launch all three agents concurrently in a single message. Pass each agent the full diff so it has the complete context.
+```text
+ONLY FIX CONFIRMED SMELLS. DO NOT BEAUTIFY BY GUESS.
+```
 
-### Agent 1: Code Reuse Review
+没有证据的 reviewer finding 只是线索，不是命令。先验证，再修改。
 
-For each change:
+## Phase 1: 识别变更
 
-1. **Search for existing utilities and helpers** that could replace newly written code. Look for similar patterns elsewhere in the codebase — common locations are utility directories, shared modules, and files adjacent to the changed ones.
-2. **Flag any new function that duplicates existing functionality.** Suggest the existing function to use instead.
-3. **Flag any inline logic that could use an existing utility** — hand-rolled string manipulation, manual path handling, custom environment checks, ad-hoc type guards, and similar patterns are common candidates.
+1. 优先读取当前变更：
+   - 有 staged diff：跑 `git diff --cached` 和 `git diff`
+   - 无 staged diff：跑 `git diff HEAD`
+   - 如果没有 git diff，审查本轮对话中用户点名或你刚编辑过的文件
+2. 记录 diff 范围：
+   - changed files
+   - affected modules
+   - stack signals: `package.json` / `pyproject.toml` / `go.mod` / `Cargo.toml` / etc.
+   - test framework signals: `jest` / `vitest` / `pytest` / `go test` / etc.
+   - scope flags: API / auth / backend / frontend / migration / docs / release
+   - related `planning/tasks.md` / `change-meta.json` / capability specs
+   - already-run verification, if any
+3. 如果变更跨多个互不相关模块，先按模块分组；不要让一个 cleanup pass 变成大扫除。
+4. 只审当前 diff 新增或本次改动扩大后的坏味道。历史债只在它阻挡当前交付或被本次 diff 放大时进入清理范围。
 
-### Agent 2: Code Quality Review
+## Phase 2: Codex 智能体评审
 
-Review the same changes for hacky patterns:
+如果当前环境支持 Codex 多智能体，并且用户已经明确触发 `cc-simplify` 或要求并行评审，可以构建只读评审智能体。
 
-1. **Redundant state**: state that duplicates existing state, cached values that could be derived, observers/effects that could be direct calls
-2. **Parameter sprawl**: adding new parameters to a function instead of generalizing or restructuring existing ones
-3. **Copy-paste with slight variation**: near-duplicate code blocks that should be unified with a shared abstraction
-4. **Leaky abstractions**: exposing internal details that should be encapsulated, or breaking existing abstraction boundaries
-5. **Stringly-typed code**: using raw strings where constants, enums (string unions), or branded types already exist in the codebase
-6. **Unnecessary JSX nesting**: wrapper Boxes/elements that add no layout value — check if inner component props (flexShrink, alignItems, etc.) already provide the needed behavior
-7. **Unnecessary comments**: comments explaining WHAT the code does (well-named identifiers already do that), narrating the change, or referencing the task/caller — delete; keep only non-obvious WHY (hidden constraints, subtle invariants, workarounds)
-8. **Spec drift**: behavior, boundary, or invariant changed but no matching `change-meta.json` / capability spec delta was updated — flag it explicitly and propose the missing spec sync
+### 调度原则
 
-### Agent 3: Efficiency Review
+- Codex 中优先使用 `spawn_agent(agent_type="explorer")` 创建只读评审智能体。
+- 如果当前环境没有 `explorer`，使用默认智能体也必须在 prompt 里写明：只读审查，不编辑文件。
+- 只把只读评审交给智能体；主线程负责最终判断和实际编辑。
+- 每个智能体拿到同一份完整 diff、相关任务/设计/spec 路径、当前 repo 根目录。
+- 智能体不能改文件，只输出结构化 findings。
+- 如果没有多智能体能力，主线程按同样清单顺序执行。
+- 小 diff 不强制开智能体：少于约 50 行且只触碰单一文件时，主线程执行同一清单即可。
+- 条件 specialist 只在对应 scope 出现时启用；不要为了“完整”启动无关评审。
 
-Review the same changes for efficiency:
+智能体 prompt 必须自包含：
 
-1. **Unnecessary work**: redundant computations, repeated file reads, duplicate network/API calls, N+1 patterns
-2. **Missed concurrency**: independent operations run sequentially when they could run in parallel
-3. **Hot-path bloat**: new blocking work added to startup or per-request/per-render hot paths
-4. **Recurring no-op updates**: state/store updates inside polling loops, intervals, or event handlers that fire unconditionally — add a change-detection guard so downstream consumers aren't notified when nothing changed. Also: if a wrapper function takes an updater/reducer callback, verify it honors same-reference returns (or whatever the "no change" signal is) — otherwise callers' early-return no-ops are silently defeated
-5. **Unnecessary existence checks**: pre-checking file/resource existence before operating (TOCTOU anti-pattern) — operate directly and handle the error
-6. **Memory**: unbounded data structures, missing cleanup, event listener leaks
-7. **Overly broad operations**: reading entire files when only a portion is needed, loading all items when filtering for one
+```text
+你是 cc-simplify 的只读评审智能体。不要编辑文件。
+输入：repo root、完整 diff、相关任务/spec 路径、你的评审维度。
+输出：每行一个 JSON finding；没有发现时只输出 NO FINDINGS。
+没有证据的猜测不要输出为 finding。
+```
 
-## Phase 3: Fix Issues
+Finding JSONL schema：
 
-Wait for all three agents to complete. Aggregate their findings and fix each issue directly. If a finding is a false positive or not worth addressing, note it and move on — do not argue with the finding, just skip it.
+```json
+{"severity":"critical|important|minor","confidence":8,"path":"file","line":12,"category":"reuse|scope|quality|efficiency|testing|security|api-contract|release","summary":"...","evidence":"...","fix":"...","fingerprint":"file:12:category","specialist":"name","test_stub":"optional"}
+```
 
-When done, briefly summarize what was fixed (or confirm the code was already clean).
+字段要求：
+
+- 必填：`severity`、`confidence`、`path`、`category`、`summary`、`evidence`、`fix`、`specialist`
+- 可选：`line`、`fingerprint`、`test_stub`
+- `confidence` 用 1-10；低于 5 的 finding 不能进入自动修复列表。
+- `test_stub` 只给能用一个小测试抓住的问题；架构判断不要伪造测试。
+
+### 推荐三个智能体
+
+#### Agent A: Spec / Scope Reviewer
+
+目标：确认实现是否仍然符合冻结的需求边界。
+
+检查：
+
+1. 是否遗漏了任务要求。
+2. 是否多做了未要求功能。
+3. 是否改变行为、边界或 invariant，却没有同步 `change-meta.json` 或 capability spec。
+4. 是否把 bug 修复伪装成新需求，或把新需求伪装成 cleanup。
+5. 是否应该 reroute：
+   - 设计范围变了 -> `cc-plan`
+   - 根因故事失效 -> `cc-investigate`
+   - 需要重新验证 -> `cc-check`
+
+#### Agent B: Reuse / Structure Reviewer
+
+目标：删除重复和无意义抽象。
+
+检查：
+
+1. 新增函数是否重复现有 helper、utility、shared module、邻近文件里的模式。
+2. 是否手写了已有能力：路径处理、字符串解析、env 检测、类型 guard、schema 验证、错误包装。
+3. 是否出现 copy-paste with slight variation，应该合并为已有 helper 或一个更小的局部函数。
+4. 是否有 parameter sprawl：为了一个场景继续给函数加参数，而不是整理输入对象或拆出职责。
+5. 是否泄漏抽象边界：调用方知道了内部状态、文件布局、协议细节或测试专用机制。
+6. 文件是否因为本次改动开始承担多个职责；如果只是历史遗留，不在本轮扩大范围。
+
+#### Agent C: Quality / Efficiency / Test Reviewer
+
+目标：找出会变成维护成本或运行成本的坏味道。
+
+检查：
+
+1. 冗余状态：缓存可派生值、重复状态源、无意义 observer/effect。
+2. 热路径膨胀：启动、请求、渲染、轮询、事件处理里新增阻塞工作。
+3. 重复 IO / 网络 / API 调用、N+1、整文件读取但只需要局部数据。
+4. missed concurrency：互不依赖的读文件、搜索、请求、验证命令被串行执行。
+5. recurring no-op update：轮询或 reducer 明明没有变化却通知下游。
+6. TOCTOU：先检查文件存在再操作；应直接操作并处理错误。
+7. 内存和生命周期：无界数组/map/cache、listener 未清理、timer 未释放。
+8. 测试坏味道：
+   - 测 mock 存在，不测真实行为
+   - 为测试给生产类加 test-only method
+   - 不理解依赖副作用就 mock
+   - partial mock 缺少真实响应字段
+   - 只补测试后验通过，没有证明测试会抓住 bug
+   - 缺少错误路径、权限拒绝、空值、边界值、单元素集合、并发访问测试
+   - 测试共享全局状态、依赖系统时间/时区/locale、真实网络或随机数据但没有 seed
+   - 断言无序结果的顺序，或使用过紧 timeout 造成 flaky
+
+### 条件 specialist
+
+当 diff 命中对应范围时，额外启用这些只读维度；没有命中就跳过：
+
+- `security`：auth/backend 大改、用户输入、文件路径、命令执行、HTML escape hatch、token/secret 处理
+- `api-contract`：endpoint、请求/响应字段、状态码、鉴权要求、分页、OpenAPI/SDK 文档
+- `release`：VERSION、CHANGELOG、发布脚本、CI artifact、tag 格式、publish idempotency
+- `frontend-performance`：渲染循环、列表查找、重复 style 注入、bundle/懒加载边界
+
+如果任一 specialist 发现 `critical`，再做一次 Red Team 只读复查：它只找遗漏的跨边界失败模式，不重复前面 finding。
+
+## Phase 3: 汇总和去重 findings
+
+先解析 JSONL；非 JSON 行丢弃，`NO FINDINGS` 表示该 source 没有发现。
+
+Fingerprint 规则：
+
+1. 优先使用 finding 自带 `fingerprint`。
+2. 否则用 `{path}:{line}:{category}`。
+3. 没有 `line` 时用 `{path}:{category}:{summary}`。
+
+同一 fingerprint 的 finding 合并：
+
+- 保留 confidence 最高的版本。
+- 如果多个 specialist 命中同一问题，标记 `multi-specialist`，confidence +1，最高 10。
+- 合并后按 `critical -> important -> minor`，再按 confidence 降序排序。
+
+Confidence gate：
+
+- `7-10`：进入主 findings 表。
+- `5-6`：进入主表，但 Decision 初始为 `verify-first`。
+- `3-4`：放到 appendix，只在主线程读代码后确认时升级。
+- `1-2`：抑制，不输出为行动项。
+
+主表格式：
+
+| ID | Source | Severity | File:line | Claim | Evidence | Proposed fix | Decision |
+| --- | --- | --- | --- | --- | --- | --- | --- |
+| S1 | spec | critical | | | | | pending |
+
+Severity：
+
+- `critical`: 会破坏功能、安全、数据、发布真实性
+- `important`: 明显坏味道、spec drift、测试假象、性能风险
+- `minor`: 可读性、局部重复、小优化
+
+Decision：
+
+- `auto-fix`: 已确认、机械、低风险，主线程可直接修
+- `ask`: 需要用户判断或会改变用户可见行为
+- `fix`: 已确认且在当前 cleanup 边界内
+- `verify-first`: 线索合理但证据不足，修前必须读代码确认
+- `skip-false-positive`: 和代码事实不符
+- `skip-not-worth-it`: 成本高于收益，且不影响当前交付
+- `reroute`: 已经不是 simplify 范围
+
+### Fix-First 决策表
+
+默认自动修：
+
+- dead code、unused variable/import、明显 stale comment
+- 简单重复 helper、路径/版本/changelog 不一致
+- 局部 magic value 提取为已存在常量或邻近常量
+- 明显 O(n*m) 查找可改为 map/index，且行为不变
+- 缺少轻量输入 shape 校验，且已有本地校验模式可复用
+
+默认 ask 或 reroute：
+
+- auth、XSS、注入、secret、权限、安全边界
+- race condition、数据迁移、事务语义、enum/value completeness
+- 需要超过约 20 行的新设计，或触碰超过 5 个文件
+- 删除功能、改变公共 API、改变用户可见行为
+- finding 证明 frozen plan、root cause、acceptance 已经失效
+
+## Phase 4: 验证 finding 是否成立
+
+不要盲信 reviewer。
+
+每条 finding 修复前先做四个检查：
+
+1. **代码事实**：打开对应文件和相邻实现，确认问题真实存在。
+2. **使用事实**：用 `rg` 查调用方，确认不是 reviewer 缺上下文。
+3. **需求事实**：对照 `planning/tasks.md`、`change-meta.json`、capability spec，确认没有误删必要行为。
+4. **验证事实**：明确修复后用什么命令或检查证明没有回归。
+
+如果 reviewer 建议“更专业”的能力，先做 YAGNI 检查：没有调用方、没有需求、没有 acceptance，就不要新增。
+
+这些情况不要报成 finding：
+
+- 为可读性保留的轻微重复。
+- 已有断言已经覆盖真实行为，只是“不够漂亮”。
+- 输入域受约束，所谓边界值在产品里不可能出现。
+- 测试一次覆盖多个 guard；只要行为清楚，不必强拆。
+- 当前 diff 已经修掉的问题。
+- shutdown/emergency/fire-and-forget 路径里有意吞掉错误。
+- pass-through wrapper 只是稳定 API 层，内部委托到真实实现。
+
+## Phase 5: 只修 confirmed smells
+
+修复顺序：
+
+1. Critical
+2. Simple important fixes
+3. Complex important fixes
+4. Minor fixes only if low-risk
+
+边界：
+
+- 不做 unrelated refactor。
+- 不改公共 API，除非 finding 证明当前 API 本身就是坏味道。
+- 不把多个架构方向揉进一个 cleanup。
+- 不为了消灭 3 行重复制造 50 行抽象。
+- 如果预计触碰超过 5 个文件，先停下说明：拆分、reroute，还是只修 critical path。
+
+如果某条 finding 需要重新设计，停止并交给 `cc-plan`。如果 finding 证明根因不明，交给 `cc-investigate`。
+
+## Phase 6: 新鲜验证
+
+完成修改后必须运行和本次 cleanup 相关的最小验证：
+
+1. 格式/结构：例如 `git diff --check`、JSON/YAML parse、脚本 `bash -n`。
+2. 目标测试：覆盖被修改模块的单测或 smoke。
+3. 必要时运行更高层 gate：`npm test`、`npm run verify:*`、项目本地等价命令。
+
+不能用旧结果声称现在通过。智能体报告也不能替代主线程验证。
+
+## 输出格式
+
+结束时输出简短 `Simplify Report`：
+
+- Reviewed diff:
+- Agents used: `yes` / `no`
+- Findings fixed:
+- Findings skipped:
+- Reroutes / blockers:
+- Verification run:
+- Next step: `cc-check` / `cc-act` / `cc-plan` / `cc-investigate`
+
+如果 `cc-simplify` 修改了代码或验证口径，下一步必须回 `cc-check`，不能带旧 report-card 继续 `cc-act`。
+
+## Do Not
+
+- 不把 cleanup 当成重写入口。
+- 不因为 reviewer 说了就盲改。
+- 不把风格偏好升级成 critical。
+- 不跳过 spec drift。
+- 不用 mock 通过来证明真实行为正确。
+- 不在没有新鲜验证时声称“已简化完成”。

package/CHANGELOG.md

@@ -9,6 +9,42 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0
 
 ## [Unreleased]
 
+## [4.5.2] - 2026-04-28
+
+### Skill Review Hardening
+
+v4.5.2 strengthens the verification and cleanup side of the workflow so
+review, QA, investigation, release readiness, and pre-ship simplification carry
+fresh evidence instead of relying on stale chat context.
+
+### Changed
+
+- Updated `cc-check` to record review freshness, specialist review facets, QA coverage/browser evidence, and runtime failure ownership before a verdict can enter `cc-act`.
+- Updated `cc-act` to render a readiness dashboard, check PR body accuracy, and rerun verification on each invocation while keeping ship actions idempotent.
+- Updated `cc-investigate` to require a frozen root-cause contract with prior-history checks, boundary probes, backward trace, reference comparison, diagnostic probe cleanup, condition-wait evidence, pattern analysis, sanitized research evidence, and repair-boundary blast-radius fields.
+- Updated `cc-simplify` to a Chinese Codex-native cleanup workflow with scope-aware reviewer dispatch, JSONL findings, confidence-gated deduplication, Fix-First decisions, false-positive suppressions, and fresh validation evidence.
+- Refreshed public examples and skill binding metadata for `cc-investigate@1.1.4`, `cc-check@1.8.4`, `cc-act@1.6.4`, and `cc-simplify@1.3.0`.
+
+## [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.