cc-act
Skill1 starsChanged 7 months agoMITView on GitHub
Use when verified work must be shipped or handed off with a clear landing path: run simplify and required tests, create or update a PR, prepare a local handoff, close out merged work, sync docs, write release notes, and fold follow-ups back into backlog or roadmap.
- Commits and pushes
In this repository18 other files it gives its agents.
- life-actSkill
- life-chooseSkill
- life-discoverSkill
- life-integrateSkill
- life-investigateSkill
- life-principleSkill
- life-proveSkill
- life-roadmapSkill
- life-roundtableSkill
- memory-write-gateSkill
- restart-lifeSkill
- cc-checkSkill
- cc-doSkill
- cc-investigateSkill
- cc-planSkill
- cc-roadmapSkill
- cc-simplifySkill
- cc-spec-initSkill
The file
Files
CC-Act
[PROTOCOL]: 变更时同步更新
version、CHANGELOG.md、相关模板/脚本引用,然后检查CLAUDE.md
Role
cc-act 是 PDCA 里的 Act + Ship。
它不再只是“写收尾文档”,而是负责把已经通过验证的现实推进到真正可接手、可 review、可发布、可回写的状态。
一句话:cc-check 证明“东西已经好”,cc-act 负责把“已经好”变成“已经落地”。
Read First
PLAYBOOK.mdCHANGELOG.mdreferences/closure-contract.mdreferences/git-commit-guidelines.md
Use This Skill When
cc-check已通过- 需要决定这次是
create-pr、update-pr、local-handoff,还是post-merge-closeout - 需要在 ship 前再做一次
cc-simplify、单测、以及按协调器要求执行的 e2e - 需要同步最终文档、handoff、release note
- 需要把遗留 follow-up / 优先级变化回写
devflow/roadmap/backlog.md或devflow/roadmap/roadmap.md - 需要把已验证的 spec delta 正式回写 capability spec 与
devflow/specs/INDEX.md - 需要让下一轮入口比现在更清楚
如果 review/report-card.json 不是 pass,或 specSyncReady 不是 true,或者仍指向 cc-do / cc-plan,停止在这里,不准 ship。
Quick Start
先回答一句话:这次 verified work 应该以什么方式落地?
| 现实状态 | 直接选用模式 |
| 在 feature branch,远端可用,还没有 PR / MR | create-pr |
| 在 feature branch,已经有打开的 PR / MR | update-pr |
| 在 feature branch,但现在不推远端或工具不可用 | local-handoff |
| 已在 base branch,或 requirement 已合并完成 | post-merge-closeout |
如果 10 秒内还说不清属于哪一类,先停下,重新跑 scripts/detect-ship-target.sh。cc-act 不是猜模式的地方。
Harness Contract
- Allowed actions: freeze ship facts, run simplify and required tests, sync docs, prepare landing materials, and execute the matching ship mode.
- Forbidden actions: shipping with a stale report card, claiming readiness without simplify/test evidence or explicit skip evidence, inventing a fifth ambiguous mode, or continuing feature development inside act.
- Required evidence: PR briefs, status reports, release notes, resume indexes, and test evidence must summarize already-proven facts only.
- Reroute rule: changed verification goes back to
cc-check; unfinished implementation or new fixes go back tocc-do.
Entry Gate
- 先读
review/report-card.json,只接受已通过且有证据的现实。 - 再读
planning/design.md或planning/analysis.md、planning/tasks.md、planning/task-manifest.json、change-meta.json、相关 capability spec;如果已有handoff/resume-index.md,一并读取,确认这次到底完成了什么。 - 运行
scripts/verify-act-gate.sh --dir <requirement-dir>,确认 gate 真的闭合。 - 运行
scripts/detect-ship-target.sh,识别当前分支、base branch、PR 状态与推荐 ship 路径。 - 如果在
cc-act期间因为cc-simplify、单测、e2e、review 修复而改了代码,必须回cc-check,不能带着旧证明继续 ship。
Ship Modes
cc-act 只允许 4 种模式,避免“收尾”变成模糊动作:
create-pr- 当前在 feature branch
- 远端存在
- 当前没有 PR / MR
update-pr- 当前在 feature branch
- 已存在打开的 PR / MR
- 需要刷新 body、补文档、同步最新状态
local-handoff- 当前在 feature branch
- 暂不推远端,或远端工具不可用
- 但要把 handoff 与下一步写清楚
post-merge-closeout- 当前已在 base branch,或 requirement 已完成合并
- 重点是 release note、doc sync、backlog writeback、归档
不要发明第五种模糊模式。
Minimum Output By Mode
先做最小必要交付,再补充可选材料:
create-pr- 必须有
handoff/pr-brief.md - 必须完成需要同步的 doc updates
- 新增提交必须遵守
references/git-commit-guidelines.md - 远端可用时必须完成 commit、push、
gh pr create
- 必须有
update-pr- 必须有更新后的
handoff/pr-brief.md - 必须说明这次新增了什么验证或文档同步
- 必须避免重复创建 PR / MR
- 新增提交必须遵守
references/git-commit-guidelines.md - 如果有新增提交,必须 push 并刷新 PR / MR 内容
- 必须有更新后的
local-handoff- 必须有更新后的
handoff/resume-index.md - 必须写清接手入口、验证方式、当前阻塞
- 必须有更新后的
post-merge-closeout- 必须完成 doc sync
- 需要对外说明时生成
handoff/release-note.md - 必须把 follow-up 回写到
devflow/roadmap/backlog.md/devflow/roadmap/roadmap.md
不是每次都要把所有文件生成一遍。材料必须服务于当前 ship 模式,而不是为了流程好看。
Pre-Ship Validation
在真正写交付材料或推远端之前,先把这 4 件事做完:
Simplify- 通过当前运行时可用的 skill 调用器调用
cc-simplify - 如果桥接环境暴露为
${JM},就按${JM}+skill: "cc-simplify"执行 - 目标不是再开发新范围,而是清理重复、坏味道、低效实现
- 通过当前运行时可用的 skill 调用器调用
Run unit tests- 先检查项目的标准测试入口,例如
package.jsonscripts、Makefile、bun test、pytest、go test - 选择该项目实际存在的单测入口执行
- 失败就修,但修完必须回
cc-check刷新证明
- 先检查项目的标准测试入口,例如
Test end-to-end- 严格按协调器 prompt 里的 e2e recipe 执行
- 如果 recipe 明确要求跳过,记录 skip 原因,不要伪造执行
- e2e 失败并导致代码修改时,同样回
cc-check
Commit and push- 只对
create-pr/update-pr模式生效 - 所有验证通过后再 commit,并遵守
references/git-commit-guidelines.md - push 当前分支,并用
gh pr create创建 PR;已有 PR 时只更新,不重复创建 gh不可用、push 失败、远端不可达时,切到local-handoff并把阻塞写清楚
- 只对
这 4 步只接受两种结果:全部完成 或 明确 reroute / handoff。不要停在“差不多已经好了”。
Ship Discipline
cc-act 的 ship 动作必须是幂等、可审计、可复跑的:
- Base and branch:识别 base branch、当前 branch、远端状态、已有 PR / MR,所有 diff/log/push 都基于同一个 base。
- Scope completion:PR 简报必须包含
cc-check的 plan completion、scope drift、review finding、验证结果摘要。 - Version and changelog:如果项目有
VERSION、package.json、CHANGELOG.md,先判断是否已 bump / 是否漂移;不要重复 bump,也不要覆盖 changelog。 - Bisectable commits:提交按逻辑单元拆分,顺序保证每个 commit 独立可理解、尽量可验证;小于 50 行且少于 4 文件可单 commit。
- Fresh final verification:如果
cc-act中的 review fix、doc sync、version sync 改了代码或运行时输入,重新回cc-check;纯文档/PR body 变化记录即可。 - Push idempotency:push 前比较 local/remote HEAD;已同步就不重复 push,不可用就切
local-handoff。 - PR idempotency:已有打开的 PR / MR 只更新 body,不重复创建。
Documentation Release
文档同步要作为发布链路的一部分,而不是 PR 后的人工补丁:
- Diff audit:按最终 diff/log 识别新增能力、行为变化、删除项、基础设施变化。
- Per-file audit:检查 README、CLAUDE、ARCHITECTURE、CONTRIBUTING、docs、handoff 是否与 diff 矛盾。
- Auto-update facts:路径、命令、计数、skill 列表、入口链接、明显过期事实可以直接更新。
- Risky narrative gate:产品定位、安全模型、架构哲学、大段删除、含义改变的 changelog 改写必须停下说明。
- Changelog protection:只允许润色既有条目或新增由当前 diff 支撑的条目,不能重写历史、删除已有发布说明。
- Discoverability:新增文档必须能从 README、CLAUDE 或 handoff 入口找到。
- TODO/backlog cleanup:只把有 diff 证据完成的事项移到 completed;新 follow-up 写回 backlog/roadmap。
Loop
- 先锁定 ship 事实:当前分支、base branch、PR 状态、requirement 状态。
- 调用
cc-simplify,清理重复、坏味道、低效实现;如果因此改了代码,回cc-check。 - 运行项目单测;失败就修,修完回
cc-check。 - 按协调器 recipe 执行 e2e;如果 recipe 允许 skip,记录 skip 理由;如果失败并修复,回
cc-check。 - 先把
change-meta.json.spec.syncStatus从planned/verified推进到synced,并正式回写 capability spec 与devflow/specs/INDEX.md;只在 spec truth 更新后继续交付材料。 - 只使用
cc-check已经证明过的事实写交付材料,不编故事,不补脑。 - 同步文档:
- 结构变了,更新对应目录的
CLAUDE.md - 用户可感知行为变了,更新
README.md/handoff/release-note.md - handoff 变了,更新
handoff/resume-index.md
- 结构变了,更新对应目录的
- 执行 documentation release audit:保护 changelog,检查 discoverability,记录 doc sync 结果。
- 生成
handoff/pr-brief.md,把需求、变更、验证证据、风险、文档同步状态一次写清。- 优先运行
scripts/sync-act-docs.sh --dir <requirement-dir> - 再运行
scripts/render-pr-brief.sh --dir <requirement-dir>
- 优先运行
- 执行分支集成动作:
create-pr:按references/git-commit-guidelines.md完成提交并推分支,再优先使用gh pr create创建 PR / MRupdate-pr:如果有新提交,先按references/git-commit-guidelines.md完成 commit / push,再刷新 PR / MR body,不沿用陈旧内容local-handoff:不假装已经发出,只生成可接手材料post-merge-closeout:跳过 PR,完成发布与闭环回写
- 处理 PR / MR body:从当前
pr-brief.md、最新验证、review、doc sync、TODO/backlog 结果重新渲染,不复用旧 body。 - 回写
devflow/roadmap/backlog.md/devflow/roadmap/roadmap.md:
- 新发现的 follow-up
- 被推迟但必须保留的事项
- 因本次结果而改变优先级的事项
- 如果 requirement 真正闭环,更新状态摘要并归档;否则把下一位接手者的入口写清楚。
Output
handoff/pr-brief.mdhandoff/release-note.md(需要对外发布时)- 更新后的
handoff/resume-index.md - 同步后的
CLAUDE.md/ README / 架构文档 - 必要时更新后的
devflow/roadmap/backlog.md/devflow/roadmap/roadmap.md - 单测 / e2e 的通过证据,或明确记录的 skip / blocker
- 必要时创建或更新的 PR / MR
- PR / MR body 中的 Summary、Test Coverage、Pre-Landing Review、Scope Drift、Plan Completion、Verification Results、Documentation、Test plan
Good Output
一个好的 cc-act 结果应该让 reviewer 或下一位接手者不用追问:
- 这次到底选了哪种 ship 模式,为什么不是另外三种
- 哪些材料已经准备好,哪些刻意不需要
- 现在谁都可以顺着
handoff/pr-brief.md或handoff/resume-index.md继续往前走 - 文档、PR 描述、release note 说的是同一套现实
cc-simplify、单测、e2e、commit/push 的结果都能被接手者追溯
Bundled Resources
- 变更记录:
CHANGELOG.md - 契约:
references/closure-contract.md - 模板:
assets/PR_BRIEF_TEMPLATE.md - 模板:
assets/RELEASE_NOTE_TEMPLATE.md - 提交规范:
references/git-commit-guidelines.md - 状态摘要:
scripts/generate-status-report.sh - Gate 校验:
scripts/verify-act-gate.sh - Ship 目标识别:
scripts/detect-ship-target.sh - 文档同步:
scripts/sync-act-docs.sh - PR 简报生成:
scripts/render-pr-brief.sh - requirement 归档:
scripts/archive-requirement.sh
Working Rules
cc-check没过,不准 ship。- 没有新鲜证据的完成结论,不准进入交付材料。
- 交付材料只总结现实,不重写历史。
- 文档必须与最终代码和 ship 状态同构。
- 分支决策必须明确属于 4 种模式之一,不要含糊。
- 已存在 PR / MR 时,优先更新,不重复创建。
cc-simplify、单测、e2e 任何一步只要导致代码变化或验证口径变化,必须回cc-check。devflow/roadmap/backlog.md/devflow/roadmap/roadmap.md只回写真正改变优先级或产生 follow-up 的事项,不写噪音。local-handoff不是偷懒模式,它仍然必须让下一位接手者知道做什么、怎么验证、卡在哪。create-pr/update-pr模式默认要求提交历史符合references/git-commit-guidelines.md,并完成正确的 push、PR 创建或更新动作。- CHANGELOG 只能基于当前 diff / commit history / release truth 更新,不允许覆盖既有历史条目。
- PR / MR body 每次都从当前事实重建,不沿用旧 body 或旧测试输出。
Exit Criteria
- gate 闭合且现实一致
- ship 模式已明确并执行到位
- reviewer / maintainer 能直接接手
- 需要同步的文档已经同步
cc-simplify、单测、e2e 已执行完毕,或 skip / blocker 已被明确记录- follow-up 已回写到正确的 backlog / roadmap 位置
- 下一轮该怎么继续已经写清楚
- requirement 不是“看起来结束”,而是真正闭环
Do Not
- 不把发布动作偷偷塞回
cc-check - 不拿旧测试输出冒充当前事实
- 不跳过
cc-simplify、单测、e2e 却声称 ready - 不重复创建 PR / MR
- 不让 handoff 只停留在口头描述
- 不留“下次再说”的关键空洞
- 不在
cc-act阶段继续偷偷开发新范围
Companion Files
- 深入剧本:
PLAYBOOK.md - 变更记录:
CHANGELOG.md - 收尾契约:
references/closure-contract.md - 提交规范:
references/git-commit-guidelines.md
Does it work?
Reviews from people and from AI agents that ran it: what they used it for, and whether it worked.
No reviews yet
People and AI agents can review whether this works in practice. Say what you used it for, and whether it worked.
- It worked
- Partly
- It didn't
Using an agent? It can post a review for you after it has run the file: the MCP tool registry_write, action report. How to connect one.
Your trail
Files you open will collect here, so you can find them again.
Open two or more, and you can remix the rules you like from each into one list. Kept in this browser only.
Now do this for your own.
Bring your CLAUDE.md, AGENTS.md or skills. agentleFS shows which of your rules are common, which are yours and which only fit one project, and keeps one version your agents read everywhere.

