cc-devflow 4.3.0 → 4.4.1

package/.claude/skills/cc-investigate/assets/TASK_MANIFEST_TEMPLATE.json

@@ -0,0 +1,103 @@
+{
+  "changeId": "FIX-XXX",
+  "requirementId": "FIX-XXX",
+  "requirementVersion": "FIX-XXX.v1",
+  "sourceRoadmap": {
+    "itemId": "RM-001",
+    "roadmapVersion": "1.0",
+    "roadmapSkillVersion": "2.1.0",
+    "sourceStage": "Stage 1",
+    "successSignal": "The broken behavior is reproducible and then fixed without widening scope",
+    "killSignal": "Repair requires reopening product scope or redesigning unrelated modules",
+    "dependencies": [
+      "The existing product contract still applies"
+    ],
+    "nonGoals": [
+      "No unrelated feature additions"
+    ]
+  },
+  "planningMeta": {
+    "ccInvestigateSkillVersion": "1.0.0",
+    "analysisVersion": "analysis.v1",
+    "approvedAt": "2026-04-17T12:00:00.000Z",
+    "approvedBy": "user",
+    "basedOnRootCause": "Root cause sentence"
+  },
+  "status": "planned",
+  "designMode": "cc-investigate",
+  "approvedOption": "confirmed-root-cause",
+  "designStatus": "approved",
+  "reviewStatus": "approved",
+  "spec": {
+    "primaryCapability": "cap-example",
+    "secondaryCapabilities": [],
+    "expectedDelta": [
+      "Repair capability truth without widening scope"
+    ],
+    "affectedInvariants": [],
+    "gapsClosed": [],
+    "newGaps": [],
+    "specFiles": [
+      "devflow/specs/capabilities/cap-example.md"
+    ],
+    "syncStatus": "planned",
+    "diagnosis": "implementation drift"
+  },
+  "tasteDecisions": [],
+  "userChallenges": [],
+  "currentTaskId": "T001",
+  "activePhase": 1,
+  "frozenDecisions": [
+    "Fix only the confirmed root cause",
+    "Do not widen scope without rerouting to cc-plan"
+  ],
+  "tasks": [
+    {
+      "id": "T001",
+      "title": "[TEST] Capture the bug as a failing reproduction",
+      "phase": 1,
+      "status": "pending",
+      "dependsOn": [],
+      "parallel": false,
+      "touches": [
+        "tests",
+        "bug-reproduction"
+      ],
+      "files": [
+        "src/feature/feature.test.ts"
+      ],
+      "acceptance": [
+        "The target bug is reproduced as a stable failure",
+        "The failure output points to the confirmed root-cause path"
+      ],
+      "verification": [
+        "npm test -- src/feature/feature.test.ts"
+      ],
+      "evidence": [
+        "Failing test output"
+      ],
+      "context": {
+        "readFiles": [
+          "analysis.md",
+          "tasks.md",
+          "change-meta.json"
+        ],
+        "commands": [
+          "npm test -- src/feature/feature.test.ts"
+        ],
+        "notes": [
+          "Prove the bug first",
+          "Do not change unrelated contracts in this task"
+        ]
+      },
+      "reviews": {
+        "spec": "pending",
+        "code": "pending"
+      }
+    }
+  ],
+  "openQuestions": [],
+  "deferredQuestions": [
+    "If the fix expands beyond the frozen repair boundary, reroute to cc-plan"
+  ]
+}

package/.claude/skills/cc-investigate/references/investigation-contract.md

@@ -0,0 +1,28 @@
+# Investigation Contract
+
+## Iron Law
+
+- 没有根因，不准修 bug。
+
+## Minimum Evidence
+
+每次调查至少留下这些事实：
+
+- symptom
+- reproduction path
+- expected vs actual
+- code path
+- recent change signal
+- confirmed root cause
+
+## Output Shape
+
+- `planning/analysis.md` 是人类真相源
+- `planning/tasks.md` 是修复 handoff
+- `planning/task-manifest.json` 是执行真相源
+
+## Reroute
+
+- 根因明确，修复边界清楚 -> `cc-do`
+- 发现这不是 bug，而是范围/设计问题 -> `cc-plan`
+- 发现这其实是项目优先级问题 -> `roadmap`

package/.claude/skills/cc-investigate/scripts/bootstrap-analysis.sh

@@ -0,0 +1,38 @@
+#!/usr/bin/env bash
+
+set -euo pipefail
+
+ROOT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+TEMPLATE="$ROOT_DIR/assets/ANALYSIS_TEMPLATE.md"
+REQ_DIR=""
+
+usage() {
+  cat <<'EOF'
+Usage: bootstrap-analysis.sh --dir <change-dir>
+EOF
+}
+
+while [[ $# -gt 0 ]]; do
+  case "$1" in
+    --dir) REQ_DIR="$2"; shift 2 ;;
+    -h|--help) usage; exit 0 ;;
+    *) echo "Unknown arg: $1" >&2; usage; exit 1 ;;
+  esac
+done
+
+if [[ -z "$REQ_DIR" ]]; then
+  usage
+  exit 1
+fi
+
+CHANGE_DIR="${REQ_DIR%/}"
+case "$(basename "$CHANGE_DIR")" in
+  planning|execution|review|handoff|meta)
+    CHANGE_DIR="$(dirname "$CHANGE_DIR")"
+    ;;
+esac
+
+PLANNING_DIR="$CHANGE_DIR/planning"
+mkdir -p "$PLANNING_DIR"
+cp "$TEMPLATE" "$PLANNING_DIR/analysis.md"
+echo "Wrote $PLANNING_DIR/analysis.md"

package/.claude/skills/cc-plan/CHANGELOG.md

@@ -0,0 +1,99 @@
+# CC-Plan Skill Changelog
+
+## v3.5.3 - 2026-04-25
+
+- require new planning change directories to use `REQ-<number>-<description>` for requirements and `FIX-<number>-<description>` for fixes
+- document that legacy lowercase change directories are read-only compatibility targets, not new outputs
+
+Migration note:
+
+- new plans should choose a canonical `REQ-*` or `FIX-*` change key before writing `planning/` artifacts
+
+## v3.5.2 - 2026-04-25
+
+- make test-first execution a native planning requirement so concrete tasks default to `Red -> Green -> Refactor`
+- require `planning/tasks.md` and `task-manifest.json` to expose TDD phase, failing-test evidence, refactor checkpoints, and explicit TDD exceptions
+- update planning templates and contract so `cc-plan` no longer hands a non-TDD plan to `cc-do`
+
+Migration note:
+
+- new plans should split behavior changes into `[TEST]`, `[IMPL]`, and `[REFACTOR]` tasks or document a narrow TDD exception with replacement evidence
+
+## v3.5.1 - 2026-04-25
+
+- remove external tool provenance from the public skill contract so planning rules read as native `cc-plan` behavior
+- keep the decision principles, discovery pressure, and engineering review gate unchanged while tightening skill self-description
+
+## v3.5.0 - 2026-04-24
+
+- add completeness decision principles, one-question discovery pressure, existing leverage mapping, test diagrams, failure modes, and explicit `NOT in scope` requirements
+- strengthen discovery and review contracts as native `cc-plan` behavior
+- strengthen planning contract and playbook so taste decisions, user challenges, and engineering review outputs land inside `planning/design.md` instead of new side documents
+
+Migration note:
+
+- new planning artifacts should include existing leverage, scope challenge, test diagram, failure modes, and decision classification before task generation
+
+## v3.4.0 - 2026-04-19
+
+- add `change-meta.json` as a required planning output so roadmap items, capability specs, and execution share one machine truth source
+- upgrade design and tiny-design templates with capability handoff, invariant impact, expected spec delta, and gap change sections
+- extend `task-manifest.json` and task handoff templates so `cc-do` can load capability specs without relying on chat memory
+
+Migration note:
+
+- new planning runs should generate `devflow/changes/<change-key>/change-meta.json`
+- capability-linked roadmap items should carry one explicit `Primary capability`
+
+## v3.3.0 - 2026-04-17
+
+- add structured frontmatter contract fields so cc-plan is machine-readable as a skill-first harness stage
+- add explicit `Harness Contract` and `Visible State Machine` sections to move stage orchestration into `SKILL.md` and `PLAYBOOK.md`
+- clarify reroute and recovery behavior so design reopening happens in the skill contract instead of hidden runtime assumptions
+
+Migration note:
+
+- existing requirement artifacts stay valid
+- registry and publish tooling now expect the structured frontmatter keys on the public skill
+
+## v3.2.0 - 2026-04-15
+
+- upgrade bundled templates so `DESIGN.md`, `TASKS.md`, and `task-manifest.json` teach quality by example instead of empty placeholders
+- add first-read checks that make planning density and task quality obvious to the next executor
+
+## v3.1.0 - 2026-04-15
+
+- add stronger trigger phrases in frontmatter
+- add `Quick Start` to classify planning into `clarify-first` / `tiny-design` / `full-design`
+- tighten `Good Output` so the chosen planning density is explicit on first read
+
+## v3.0.0 - 2026-04-15
+
+- 收敛 `cc-plan` 输出模型，默认交付物只保留 `DESIGN.md`、`TASKS.md`、`task-manifest.json`。
+- 把 clarification / brainstorm / review 结论并入 `DESIGN.md`，不再默认拆出独立文档。
+- 把执行 handoff 并入 `TASKS.md`，不再要求 `context-package.md` 作为 planning 产物。
+- 删除 `BRAINSTORM_TEMPLATE.md`、`CLARIFICATION_REPORT_TEMPLATE.md`、`PLAN_REVIEW_TEMPLATE.md`、`CONTEXT_PACKAGE_TEMPLATE.md`、`RESUME_INDEX_TEMPLATE.md`。
+- 删除面向旧输出模型的 clarification 脚本引用。
+
+Migration note:
+
+- 旧 requirement 目录如果已有 `BRAINSTORM.md`、`PLAN_REVIEW.md`、`context-package.md`，不要继续维护同类新文件；把仍然有效的信息吸收进 `DESIGN.md` 或 `TASKS.md`。
+- `resume-index.md` 不再属于 `cc-plan` 阶段产物，它属于 `cc-act` 的 handoff / closeout 工件。
+- `cc-do` 的默认任务上下文现在以 `DESIGN.md` + `TASKS.md` 为主，不再默认读取 `context-package.md`。
+
+## v2.0.0 - 2026-04-10
+
+- 增加 `version` frontmatter，并定义 cc-plan skill 的 semver 规则。
+- 强化 `Context Sweep`，要求在 planning 前显式读取上游 roadmap handoff、requirement 目录现状、代码与文档上下文。
+- 增加 `Source Handoff` / `Source Alignment` 约定，保证 `roadmap -> cc-plan` 的 success signal、constraints、dependencies、non-goals 不在 handoff 时丢失。
+- 升级 `BRAINSTORM.md`、`DESIGN.md`、`PLAN_REVIEW.md`、`context-package.md`、`TASKS.md`、`task-manifest.json` 模板，加入版本链和来源元数据。
+- 新增 `scripts/bump-skill-version.sh`，用于递增 skill 版本并同步 changelog。
+
+Migration note:
+
+- 旧 requirement 目录仍可继续使用，但建议补齐 requirement version、design version、source roadmap item / version 等元数据。
+- `task-manifest.json` 新增 `sourceRoadmap` 和 `planningMeta` 字段；旧消费方若只读取原有字段不会受影响。
+
+## v1.0.0 - 2026-04-10
+
+- 初始版 cc-plan skill，提供 requirement planning 基础工作流。

package/.claude/skills/cc-plan/PLAYBOOK.md

@@ -0,0 +1,106 @@
+# CC-Plan Playbook
+
+## Visible State Machine
+
+`roadmap -> cc-plan -> cc-do`
+
+- Enter from: an approved roadmap item, requirement, or bug that still needs design.
+- Stay in: `cc-plan` until the approved design and executable task breakdown are both frozen.
+- Exit to: `cc-do` only after `planning/design.md` is approved and `planning/tasks.md` plus `planning/task-manifest.json` are generated.
+- Reroute to: `roadmap` if the conversation expands back into project strategy.
+
+## Core Rules
+
+1. 先读上游 handoff，再写 planning 结论。
+2. 没有证据时写 assumption，不准冒充事实。
+3. 一次只推进一个关键未知点。
+4. `planning/design.md` 和 `planning/tasks.md` 必须足够让执行者脱离当前会话继续工作。
+5. 版本、来源、冻结决策必须可追踪。
+6. 机械决策自动落盘；taste decision 和 user challenge 必须显式交给用户拍板。
+7. 同 blast radius 内的完整边界优先做完，跨系统或无证据扩张才 defer。
+8. 具体执行计划默认测试先行；没有 Red/Green/Refactor 链或 TDD exception，不准交给 `cc-do`。
+9. 新 change 目录必须使用 `REQ-<number>-<description>` 或 `FIX-<number>-<description>`；旧小写目录只读兼容，不再作为新输出。
+
+## Required Outputs
+
+- `planning/design.md`
+- `planning/tasks.md`
+- `planning/task-manifest.json`
+
+## Local Kit
+
+- 模板全部在 `assets/`
+- 任务结构解析在 `scripts/parse-task-dependencies.js`
+- 计划边界和 placeholder 红线见 `references/planning-contract.md`
+- 变更版本时同步 `CHANGELOG.md`，必要时用 `scripts/bump-skill-version.sh`
+
+## Planning Standard
+
+1. 一份 `planning/design.md` 讲清 clarification、方案、review 和 final gate。
+2. 一份 `planning/tasks.md` 讲清执行任务和 handoff。
+3. `planning/task-manifest.json` 只做机器真相源，不再重复人类叙事。
+4. 先固定 canonical change key：需求用 `REQ-*`，修复用 `FIX-*`。
+5. 推荐方案获批前，不得生成 `planning/tasks.md`。
+6. `planning/tasks.md` 之前，`planning/design.md` 内的 review gate 必须闭合。
+7. 每个任务都要写清：
+   - 目标
+   - TDD phase：`red` / `green` / `refactor` / `exception`
+   - dependsOn / 是否允许并行
+   - 涉及文件
+   - 必读上下文
+   - 验证方式
+   - 完成证据
+8. `planning/tasks.md` 顶部必须写清 frozen decisions、commands to trust、do-not-re-decide。
+9. `planning/task-manifest.json` 必须是 `cc-do` 的真相源，而不是装饰文件。
+10. `planning/design.md` 必须包含 `Existing Leverage`、`NOT in scope`、`Failure Modes`、`Test Diagram`，除非明确说明为什么不适用。
+11. 新 artifact、CLI、包、容器、文档入口必须在计划阶段写清分发和 discoverability，不准到 `cc-act` 才发现没人能用。
+12. 行为变更任务必须拆成 `[TEST] -> [IMPL] -> [REFACTOR]` 或写明 TDD exception；不能用“实现并测试”混成一个任务。
+
+## Approval Flow
+
+1. 先写 `Source Handoff` 和 requirement framing。
+2. 在 `planning/design.md` 里记录备选方案和推荐。
+3. 用户批准推荐方案后，再冻结正式设计。
+4. 在 `planning/design.md` 里完成 review loop 与 final gate。
+5. gate 通过后，再拆 `planning/tasks.md` 与 `planning/task-manifest.json`。
+
+## Review Shape
+
+计划内的工程审查至少回答：
+
+- 现有代码已经解决了哪些子问题？
+- 最小完整方案触达哪些文件，为什么没有更小边界？
+- 数据流、状态流或执行流怎么走？
+- 每条新增 code path / user flow / error path 的第一条失败测试是什么？
+- 哪些生产失败模式已经处理，哪些 defer 到 backlog？
+
+## Design Mode Switch
+
+满足以下条件时，优先用 `tiny-design`：
+
+1. 单一功能点，小范围修改
+2. 通常只触达 1-3 个文件
+3. 不涉及 migration、复杂状态流、权限/安全、高代价回滚
+4. 执行者看完冻结卡片就能准确落地
+
+否则用 `full-design`。
+
+## Placeholder Ban
+
+这些词一出现，说明计划失败：
+
+- TODO later
+- implement later
+- add validation
+- handle edge cases
+- write tests for the above
+- similar to task N
+- TBD
+- 之后再补
+
+## Exit Rule
+
+只有当 `cc-do` 不需要临场补脑也能直接执行时，计划才算合格。
+如果执行者还得自己猜“这次到底碰哪些文件、为什么这么改”，说明 `planning/design.md` 仍然不够。
+如果执行者还看不出哪些决策已经冻结，说明 `planning/tasks.md` 仍然不够。
+如果执行者还要自己决定先写什么失败测试，说明 `planning/tasks.md` 仍然不够。