planning-with-files 维护者手册作者身份纪律、Parity 版本同步与发布流水线实践【免费下载链接】planning-with-filesPersistent file-based planning for AI coding agents and long-running tasks. Crash-proof markdown plans, session recovery after /clear and compaction, per-turn re-injection against context rot, deterministic completion gate. Manus-style. Install from npm, the Claude Code plugin marketplace, or npx skills. Codex, Cursor, OpenCode, 60 agents.项目地址: https://gitcode.com/GitHub_Trending/pl/planning-with-files本篇文章面向所有参与 planning-with-files 仓库发布release、合并merge与 Issue 处理的维护者与贡献者系统拆解仓库根目录 AGENTS.md 中沉淀的维护规则提交作者身份如何保全、版本同步Parity机制如何用脚本与测试双重锁定、发布流水线每一步如何执行、以及 2026-04-22 锁定的编排器orchestrator架构契约究竟约束了什么。读完你不仅能按规范完成一次从 Issue 到gh release create的完整发布还能理解代码和scripts/可以被发现但决策不能这一 AGENTS.md 设计初衷背后的工程理由。为什么 AGENTS.md 存在代码可发现决策不可发现AGENTS.md 开篇就点明了自身定位The code andscripts/are discoverable; this file holds the decisions that are not.代码和脚本目录本身可以探索而这份文件保存的是那些无法从代码推断出的决策。这句话解释了该文档的独特价值代码/脚本层发布所用的scripts/bump-version.py、scripts/build-clawhub-upload.py等任何维护者读代码都能看懂怎么执行决策层为什么 contributor PR 必须用cherry-pick/rebase合并而绝不能git merge --squash、为什么.continue和.gemini版本刻意滞后、为什么状态 token 必须保持英文——这些为什么只存在于 AGENTS.md。文档因此被划分为四大板块Authorship作者身份、Release flow发布流程、Formats格式规范、Repo contracts仓库契约。下文逐一展开并给出对应的源码与测试证据。作者身份纪律每一笔提交的可追溯性AGENTS.md 用Authorship一节锁定了两条提交纪律核心目标是在多贡献者协作下保持 Git 历史的真实归属。贡献者提交合并时保全 AuthorContributor commits keep the contributor asAuthor:.贡献者的提交必须保留贡献者本人的Author字段合并方式只有两种git fetch origin pull/N/head:pr-N git cherry-pick sha # 或 gh pr merge --rebase严禁对贡献者 PR 使用git merge --squash——squash 会把提交重新归属到执行本地提交的人名下。文档明确指出这一事故曾在 v2.40.1 发布周期中真实发生过一次which happened once in the v2.40.1 cycle。因此规则是squash 只允许用于自己的 WIP 提交且必须在 push 之前完成。维护者提交单一署名与 Conventional CommitsRelease 和 maintenance 提交仅由 OthmanAdi 单独署名使用 Conventional Commits 规范fix:、feat:、release:、docs:前缀且不得附加Co-Authored-By贡献者的致谢集中在三处CHANGELOG.md 的### Thanks小节、CONTRIBUTORS.md 以及 release notes绝不写进提交的 trailer 里。这一设计与 CONTRIBUTING.md 中对贡献者的要求形成闭环贡献者保持准确的 Git author 信息your commits remain part of the project history and are not treated as disposable metadata维护者则用合并纪律保证这些信息不被改写。推送禁令禁止--no-verify任何跳过钩子校验的提交都不被接受禁止对 master 的 force push唯一的例外是 tag 引用更新以及 Adi 明确授权的历史修正。发布流水线从 Issue 到 release 的七个步骤AGENTS.md 将发布流程编排为 7 步每一步都对应明确的命令与产物。以下是逐步拆解并标注了仓库内的可验证依据。第 1 步先复现再确认发布前必须完整阅读 Issue 与 PR 全文gh issue view N、gh pr view N并针对代码复现问题声明。同时要对 diff 做供应链攻击面审计检查四类风险点新增依赖new dependencies安装脚本install scriptsbin 快捷方式bin shims安装路径内新增的文件files in the install path沟通节奏也有明确要求确认问题后立即在 Issue 上评论并给出修复计划关闭评论要等发布完成后再发Never batch all communication to the end绝不把所有沟通攒到最后一次性发出。第 2 步测试闸门python -m pytest tests/ -q合并前与合并后都必须保持测试全绿。仓库根目录下 tests/ 现有 70 个 pytest 测试文件覆盖 PowerShell 编码、行尾一致性、注入确定性、会话隔离、hook 派发等横切关注点CI 在 Windows、Linux、macOS 三个平台均保持绿色。第 3 步release commit 的组成在按上文方式合并贡献者提交之后需要在其上叠加一个 release commit内容固定为四件套CHANGELOG.md 条目CONTRIBUTORS.md 更新条目、总人数、日期README.md 的版本徽章与 releases 表行版本号 bump。第 4 步用脚本 bump 版本绝不手改Bump withpython scripts/bump-version.py X.Y.Z(--dry-runfirst), never by hand.bump-version.py 是版本同步的核心工具它的存在源于一段真实历史v2.34.1、v2.36.0、v2.36.2、v2.36.3 四个版本都因手工跨 19 个文件改版本号而出现漏改某个变体的回归missed one variantregressions。脚本与测试共同构成了版本真相的唯一来源the script and the test are the source of truth, not any list in prose。Parity 集20 个条目脚本维护的PARITY_FILES列表包含类别文件规范 SKILL.mdskills/planning-with-files/SKILL.md5 个 i18n 变体skills/i18n/planning-with-files-{ar,de,es,zh,zht}/SKILL.md7 个 IDE 适配器.codebuddy、.codex、.cursor、.factory、.hermes、.mastracode、.opencode下的skills/planning-with-files/SKILL.mdAgent Skills 标准路径.agents/skills/planning-with-files/SKILL.md可选 ClawHub 暂存clawhub-upload/SKILL.mdgitignored存在时才 bump插件清单.claude-plugin/plugin.json、.claude-plugin/marketplace.json、.codex-plugin/plugin.json引文文件CITATION.cffnpm 包.pi/skills/planning-with-files/package.jsonPi 通道的版本载体刻意滞后的文件LAGGING_FILES脚本明确不自动 bump.continue与.gemini仅在显式作用域决策时 bump.kiro使用独立的-kiro版本方案如2.32.0-kiro.pi/.../SKILL.md本身无版本字段Pi 的版本就是其package.json已在上表 parity 集内捆绑的 Pi 扩展自身package.json仅当该扩展本身有变更时才随之更新。使用方式--dry-run先行预览正式执行后脚本会输出每个文件的old - new并对缺失文件报MISSING错误可选的clawhub-upload除外。脚本同时做 semver 合法性校验VERSION_RE非法版本直接返回退出码 2。测试锁定test_skill_md_version_parity.py 以规范英文 SKILL.md 的metadata.version为准绳断言所有 15 个 SKILL.md parity 文件的版本一致clawhub-upload缺失时跳过保证贡献者克隆下测试依然可绿5 个 JSON/CFF 清单的版本与规范一致其中.pi/skills/planning-with-files/package.json曾因无人锁定而停在第三方 1.1.0 长达 15 个版本见 issue #213一旦出现漂移测试失败信息会直接给出修复命令python scripts/bump-version.py canonical。第 5 步打 tag 与发布git tag vX.Y.Z # 打在 release commit 上 git push origin master --tags gh release create vX.Y.Z \ --title vX.Y.Z - short description \ --notes what changed, then Thankstag 必须打在 release commit 上release notes 的内容结构是先变更、后致谢。第 6 步多通道手动发行每次发布后发行是手动的共四条通道通道命令/操作说明ClawHubpython scripts/build-clawhub-upload.py再python scripts/build-clawhub-upload.py --verifystaged 目录必须与 tracked 清单完全一致验证通过后手动上传整个clawhub-upload/目录其 SSL 证书可能过期需确认后继续npm在.pi/skills/planning-with-files/下npm publish发布无前缀包planning-with-filesAdi 的账号废弃的tomxprime/planning-with-files与pi-planning-with-files绝不触碰skills.sh /npx skills自动自行拉取 master无需手动操作Anthropic marketplace—反映 ClawHub 上传内容build-clawhub-upload.py 的工程细节该脚本从 Git tracked 清单git ls-files构建上传暂存目录而非简单复制目录——这意味着未跟踪文件与__pycache__缓存永远不会进入发行物对应测试 test_build_clawhub_upload.py 的test_build_copies_exact_tracked_inventory_and_excludes_untracked_cache。--verify模式做三类校验精确清单missing/extraneous、逐字节一致性byte mismatch、脚本行尾.sh/.py/.ps1必须是 LFCRLF 直接 fail-closed见test_crlf_canonical_script_fails_closed_without_replacing_stage。目标路径被固定为clawhub-upload/CLI 不接受任何目标目录覆盖参数test_cli_has_no_destination_override并且拒绝管理仓库根目录之外的任何路径——供应链安全被当作一等公民。第 7 步收尾评论在 PR 与 Issue 上发布最终评论内容包含贡献者 handle、修复版本号、根因与机制、符合条件时说明you are in CONTRIBUTORS.md、以及用于自动关联的 commit SHA。然后关闭 GitHub 未自动关闭的条目。格式规范CHANGELOG、CONTRIBUTORS 与写作语气AGENTS.md 的 Formats 一节统一了所有公开产物的格式CHANGELOG## [X.Y.Z] - YYYY-MM-DD随后按### Added|Fixed|Changed|Security分类最后是### Thanks每位贡献者一行名或 handle、所做之事、Issue/PR 号。可对照 CHANGELOG.md 的 v3.17.0 条目——它完整演示了 Fixed/Security/Verification/Changed 的分类写法且对根因的描述细致到每次 hook 触发 fork 约 130 个进程的量化级别CONTRIBUTORS.md**[Name](https://github.com/handle)** — PR #N加每个贡献一条 bullet单次小修复归入 Other Contributors较大贡献归入 Major Contributions同时更新总人数与 Last updated 日期Release notes先写变更内容致谢放底部语气纪律所有公开 prose评论、注释、CHANGELOG都必须matter-of-fact就事论事——不用 em-dash—不写 Great report! 或 Thank you so much!不用 Id like to发布前跑一遍/humanizer工具过审。仓库契约2026-04-22 锁定的编排器架构AGENTS.md 的最后一部分是 Repo contracts描述的是 orchestrator编排器架构下跨 Agent 协作的不可协商约束。这三条契约与 README 中 多 Agent 运行orchestrators, workers and subagents 的设计相互印证。契约一文件所有权边界task_plan.mdandDESIGN.mdare user-owned; agents never edit them directly. Subagent returns go toprogress.md, nevertask_plan.md. Design tokens and research notes are appended tofindings.mdunder a## Design Contextheading.task_plan.md阶段计划与DESIGN.md设计文档归用户所有Agent 绝不直接编辑Subagent子代理的返回内容只能写入progress.md永远不能写入task_plan.md设计 token 与研究笔记追加到findings.md的## Design Context标题之下。这一所有权划分贯穿整个仓库的测试体系例如 test_containment.py 围绕task_plan.md的写入与解析路径做了多层隔离验证确保计划文件的内容处理边界plan root pin、嵌套根隔离符合用户拥有计划的语义。契约二Markdown on disk 是唯一共享状态Markdown on disk is the shared state across agents; no runtime-only state.磁盘上的 Markdown 文件是跨 Agent 共享状态的唯一载体不存在仅存于运行时的状态。这与项目的核心架构直接对应task_plan.md、findings.md、progress.md三文件模式就是 Agent 的工作记忆而 hooks/hooks.json 中注册的 6 个 Claude Code 生命周期钩子SessionStart、UserPromptSubmit、PreToolUse、PostToolUse、PreCompact、Stop在每一轮把磁盘状态重新注入上下文。正因为状态全在磁盘/clear、崩溃、压缩compaction都无法抹掉计划。契约三memory layer 是包裹而非替换The memory layer wrapscode-memory-router; it does not replace it.本仓库的 memory 层内存/记忆层包裹code-memory-router代码记忆路由器而不是替换它。换句话说planning-with-files 解决的是当前任务的执行状态连续性阶段、状态、依赖、完成检查而记忆路由仍然负责跨会话的事实检索——两者互补而非竞争README 的 FAQ 对 planning-with-files 与 agent memory tool 的区别 有同样表述。与 hooks 架构的呼应契约如何落地AGENTS.md 的契约不是抽象声明而是与具体钩子配置一一对应。以 Claude Code 插件为例hooks/hooks.json 注册了 6 个事件全部通过${CLAUDE_PLUGIN_ROOT}/hooks/claude-hook.sh分发事件matcher职责SessionStartstartup\|resume\|clear\|compact恢复规划上下文Restoring planning contextUserPromptSubmit—每轮注入计划上下文PreToolUseWrite\|Edit\|Bash\|Read\|Glob\|Grep工具调用前注入/提醒PostToolUseWrite\|Edit写操作后进度提醒PreCompact*压缩前刷新进度提醒Stop—完成度闸门Checking planning completion维护者若改动 hooks必须同时保持 hook 结构与 AGENTS.md 契约一致例如契约二无运行时状态意味着 hook 每次触发都从磁盘重新解析计划而不是依赖任何进程内缓存契约三则约束了 memory 层的定位。维护者工作流速查将 AGENTS.md 全文压缩为一份可执行清单合并 PRgh pr view N全文阅读 → 复现 → 供应链审计 → 立即评论确认与修复计划 →python -m pytest tests/ -q绿 →cherry-pick/--rebase合并禁 squash发 release commitCHANGELOG 条目 CONTRIBUTORS.md 更新 README 徽章/releases 表 python scripts/bump-version.py X.Y.Z --dry-run预览后正式 bump打 tag 发布tag 在 release commit 上 → push master tags →gh release create手动分发build-clawhub-upload.py--verify→ 上传 ClawHub.pi/skills/planning-with-files/下npm publishskills.sh 与 marketplace 自动跟随收尾在 PR/Issue 发布含 handle、版本、根因、致谢、SHA 的评论并关闭。这条流水线之所以被写得如此啰嗦正是因为它的每个环节都对应过真实事故v2.40.1 的 squash 归属事故、v2.34.1/v2.36.x 的漏改版本事故、v3.17.0 的 Windows hook 超时事故单次触发 fork 约 130 个进程。AGENTS.md 本质上是这个仓库用事故换来的操作手册——对任何维护者而言先读它再动手就是对这个项目最负责任的做法。【免费下载链接】planning-with-filesPersistent file-based planning for AI coding agents and long-running tasks. Crash-proof markdown plans, session recovery after /clear and compaction, per-turn re-injection against context rot, deterministic completion gate. Manus-style. Install from npm, the Claude Code plugin marketplace, or npx skills. Codex, Cursor, OpenCode, 60 agents.项目地址: https://gitcode.com/GitHub_Trending/pl/planning-with-files创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考 planning-with-files 维护者手册：作者身份纪律、Parity 版本同步与发布流水线实践
planning-with-files 维护者手册作者身份纪律、Parity 版本同步与发布流水线实践【免费下载链接】planning-with-filesPersistent file-based planning for AI coding agents and long-running tasks. Crash-proof markdown plans, session recovery after /clear and compaction, per-turn re-injection against context rot, deterministic completion gate. Manus-style. Install from npm, the Claude Code plugin marketplace, or npx skills. Codex, Cursor, OpenCode, 60 agents.项目地址: https://gitcode.com/GitHub_Trending/pl/planning-with-files本篇文章面向所有参与 planning-with-files 仓库发布release、合并merge与 Issue 处理的维护者与贡献者系统拆解仓库根目录 AGENTS.md 中沉淀的维护规则提交作者身份如何保全、版本同步Parity机制如何用脚本与测试双重锁定、发布流水线每一步如何执行、以及 2026-04-22 锁定的编排器orchestrator架构契约究竟约束了什么。读完你不仅能按规范完成一次从 Issue 到gh release create的完整发布还能理解代码和scripts/可以被发现但决策不能这一 AGENTS.md 设计初衷背后的工程理由。为什么 AGENTS.md 存在代码可发现决策不可发现AGENTS.md 开篇就点明了自身定位The code andscripts/are discoverable; this file holds the decisions that are not.代码和脚本目录本身可以探索而这份文件保存的是那些无法从代码推断出的决策。这句话解释了该文档的独特价值代码/脚本层发布所用的scripts/bump-version.py、scripts/build-clawhub-upload.py等任何维护者读代码都能看懂怎么执行决策层为什么 contributor PR 必须用cherry-pick/rebase合并而绝不能git merge --squash、为什么.continue和.gemini版本刻意滞后、为什么状态 token 必须保持英文——这些为什么只存在于 AGENTS.md。文档因此被划分为四大板块Authorship作者身份、Release flow发布流程、Formats格式规范、Repo contracts仓库契约。下文逐一展开并给出对应的源码与测试证据。作者身份纪律每一笔提交的可追溯性AGENTS.md 用Authorship一节锁定了两条提交纪律核心目标是在多贡献者协作下保持 Git 历史的真实归属。贡献者提交合并时保全 AuthorContributor commits keep the contributor asAuthor:.贡献者的提交必须保留贡献者本人的Author字段合并方式只有两种git fetch origin pull/N/head:pr-N git cherry-pick sha # 或 gh pr merge --rebase严禁对贡献者 PR 使用git merge --squash——squash 会把提交重新归属到执行本地提交的人名下。文档明确指出这一事故曾在 v2.40.1 发布周期中真实发生过一次which happened once in the v2.40.1 cycle。因此规则是squash 只允许用于自己的 WIP 提交且必须在 push 之前完成。维护者提交单一署名与 Conventional CommitsRelease 和 maintenance 提交仅由 OthmanAdi 单独署名使用 Conventional Commits 规范fix:、feat:、release:、docs:前缀且不得附加Co-Authored-By贡献者的致谢集中在三处CHANGELOG.md 的### Thanks小节、CONTRIBUTORS.md 以及 release notes绝不写进提交的 trailer 里。这一设计与 CONTRIBUTING.md 中对贡献者的要求形成闭环贡献者保持准确的 Git author 信息your commits remain part of the project history and are not treated as disposable metadata维护者则用合并纪律保证这些信息不被改写。推送禁令禁止--no-verify任何跳过钩子校验的提交都不被接受禁止对 master 的 force push唯一的例外是 tag 引用更新以及 Adi 明确授权的历史修正。发布流水线从 Issue 到 release 的七个步骤AGENTS.md 将发布流程编排为 7 步每一步都对应明确的命令与产物。以下是逐步拆解并标注了仓库内的可验证依据。第 1 步先复现再确认发布前必须完整阅读 Issue 与 PR 全文gh issue view N、gh pr view N并针对代码复现问题声明。同时要对 diff 做供应链攻击面审计检查四类风险点新增依赖new dependencies安装脚本install scriptsbin 快捷方式bin shims安装路径内新增的文件files in the install path沟通节奏也有明确要求确认问题后立即在 Issue 上评论并给出修复计划关闭评论要等发布完成后再发Never batch all communication to the end绝不把所有沟通攒到最后一次性发出。第 2 步测试闸门python -m pytest tests/ -q合并前与合并后都必须保持测试全绿。仓库根目录下 tests/ 现有 70 个 pytest 测试文件覆盖 PowerShell 编码、行尾一致性、注入确定性、会话隔离、hook 派发等横切关注点CI 在 Windows、Linux、macOS 三个平台均保持绿色。第 3 步release commit 的组成在按上文方式合并贡献者提交之后需要在其上叠加一个 release commit内容固定为四件套CHANGELOG.md 条目CONTRIBUTORS.md 更新条目、总人数、日期README.md 的版本徽章与 releases 表行版本号 bump。第 4 步用脚本 bump 版本绝不手改Bump withpython scripts/bump-version.py X.Y.Z(--dry-runfirst), never by hand.bump-version.py 是版本同步的核心工具它的存在源于一段真实历史v2.34.1、v2.36.0、v2.36.2、v2.36.3 四个版本都因手工跨 19 个文件改版本号而出现漏改某个变体的回归missed one variantregressions。脚本与测试共同构成了版本真相的唯一来源the script and the test are the source of truth, not any list in prose。Parity 集20 个条目脚本维护的PARITY_FILES列表包含类别文件规范 SKILL.mdskills/planning-with-files/SKILL.md5 个 i18n 变体skills/i18n/planning-with-files-{ar,de,es,zh,zht}/SKILL.md7 个 IDE 适配器.codebuddy、.codex、.cursor、.factory、.hermes、.mastracode、.opencode下的skills/planning-with-files/SKILL.mdAgent Skills 标准路径.agents/skills/planning-with-files/SKILL.md可选 ClawHub 暂存clawhub-upload/SKILL.mdgitignored存在时才 bump插件清单.claude-plugin/plugin.json、.claude-plugin/marketplace.json、.codex-plugin/plugin.json引文文件CITATION.cffnpm 包.pi/skills/planning-with-files/package.jsonPi 通道的版本载体刻意滞后的文件LAGGING_FILES脚本明确不自动 bump.continue与.gemini仅在显式作用域决策时 bump.kiro使用独立的-kiro版本方案如2.32.0-kiro.pi/.../SKILL.md本身无版本字段Pi 的版本就是其package.json已在上表 parity 集内捆绑的 Pi 扩展自身package.json仅当该扩展本身有变更时才随之更新。使用方式--dry-run先行预览正式执行后脚本会输出每个文件的old - new并对缺失文件报MISSING错误可选的clawhub-upload除外。脚本同时做 semver 合法性校验VERSION_RE非法版本直接返回退出码 2。测试锁定test_skill_md_version_parity.py 以规范英文 SKILL.md 的metadata.version为准绳断言所有 15 个 SKILL.md parity 文件的版本一致clawhub-upload缺失时跳过保证贡献者克隆下测试依然可绿5 个 JSON/CFF 清单的版本与规范一致其中.pi/skills/planning-with-files/package.json曾因无人锁定而停在第三方 1.1.0 长达 15 个版本见 issue #213一旦出现漂移测试失败信息会直接给出修复命令python scripts/bump-version.py canonical。第 5 步打 tag 与发布git tag vX.Y.Z # 打在 release commit 上 git push origin master --tags gh release create vX.Y.Z \ --title vX.Y.Z - short description \ --notes what changed, then Thankstag 必须打在 release commit 上release notes 的内容结构是先变更、后致谢。第 6 步多通道手动发行每次发布后发行是手动的共四条通道通道命令/操作说明ClawHubpython scripts/build-clawhub-upload.py再python scripts/build-clawhub-upload.py --verifystaged 目录必须与 tracked 清单完全一致验证通过后手动上传整个clawhub-upload/目录其 SSL 证书可能过期需确认后继续npm在.pi/skills/planning-with-files/下npm publish发布无前缀包planning-with-filesAdi 的账号废弃的tomxprime/planning-with-files与pi-planning-with-files绝不触碰skills.sh /npx skills自动自行拉取 master无需手动操作Anthropic marketplace—反映 ClawHub 上传内容build-clawhub-upload.py 的工程细节该脚本从 Git tracked 清单git ls-files构建上传暂存目录而非简单复制目录——这意味着未跟踪文件与__pycache__缓存永远不会进入发行物对应测试 test_build_clawhub_upload.py 的test_build_copies_exact_tracked_inventory_and_excludes_untracked_cache。--verify模式做三类校验精确清单missing/extraneous、逐字节一致性byte mismatch、脚本行尾.sh/.py/.ps1必须是 LFCRLF 直接 fail-closed见test_crlf_canonical_script_fails_closed_without_replacing_stage。目标路径被固定为clawhub-upload/CLI 不接受任何目标目录覆盖参数test_cli_has_no_destination_override并且拒绝管理仓库根目录之外的任何路径——供应链安全被当作一等公民。第 7 步收尾评论在 PR 与 Issue 上发布最终评论内容包含贡献者 handle、修复版本号、根因与机制、符合条件时说明you are in CONTRIBUTORS.md、以及用于自动关联的 commit SHA。然后关闭 GitHub 未自动关闭的条目。格式规范CHANGELOG、CONTRIBUTORS 与写作语气AGENTS.md 的 Formats 一节统一了所有公开产物的格式CHANGELOG## [X.Y.Z] - YYYY-MM-DD随后按### Added|Fixed|Changed|Security分类最后是### Thanks每位贡献者一行名或 handle、所做之事、Issue/PR 号。可对照 CHANGELOG.md 的 v3.17.0 条目——它完整演示了 Fixed/Security/Verification/Changed 的分类写法且对根因的描述细致到每次 hook 触发 fork 约 130 个进程的量化级别CONTRIBUTORS.md**[Name](https://github.com/handle)** — PR #N加每个贡献一条 bullet单次小修复归入 Other Contributors较大贡献归入 Major Contributions同时更新总人数与 Last updated 日期Release notes先写变更内容致谢放底部语气纪律所有公开 prose评论、注释、CHANGELOG都必须matter-of-fact就事论事——不用 em-dash—不写 Great report! 或 Thank you so much!不用 Id like to发布前跑一遍/humanizer工具过审。仓库契约2026-04-22 锁定的编排器架构AGENTS.md 的最后一部分是 Repo contracts描述的是 orchestrator编排器架构下跨 Agent 协作的不可协商约束。这三条契约与 README 中 多 Agent 运行orchestrators, workers and subagents 的设计相互印证。契约一文件所有权边界task_plan.mdandDESIGN.mdare user-owned; agents never edit them directly. Subagent returns go toprogress.md, nevertask_plan.md. Design tokens and research notes are appended tofindings.mdunder a## Design Contextheading.task_plan.md阶段计划与DESIGN.md设计文档归用户所有Agent 绝不直接编辑Subagent子代理的返回内容只能写入progress.md永远不能写入task_plan.md设计 token 与研究笔记追加到findings.md的## Design Context标题之下。这一所有权划分贯穿整个仓库的测试体系例如 test_containment.py 围绕task_plan.md的写入与解析路径做了多层隔离验证确保计划文件的内容处理边界plan root pin、嵌套根隔离符合用户拥有计划的语义。契约二Markdown on disk 是唯一共享状态Markdown on disk is the shared state across agents; no runtime-only state.磁盘上的 Markdown 文件是跨 Agent 共享状态的唯一载体不存在仅存于运行时的状态。这与项目的核心架构直接对应task_plan.md、findings.md、progress.md三文件模式就是 Agent 的工作记忆而 hooks/hooks.json 中注册的 6 个 Claude Code 生命周期钩子SessionStart、UserPromptSubmit、PreToolUse、PostToolUse、PreCompact、Stop在每一轮把磁盘状态重新注入上下文。正因为状态全在磁盘/clear、崩溃、压缩compaction都无法抹掉计划。契约三memory layer 是包裹而非替换The memory layer wrapscode-memory-router; it does not replace it.本仓库的 memory 层内存/记忆层包裹code-memory-router代码记忆路由器而不是替换它。换句话说planning-with-files 解决的是当前任务的执行状态连续性阶段、状态、依赖、完成检查而记忆路由仍然负责跨会话的事实检索——两者互补而非竞争README 的 FAQ 对 planning-with-files 与 agent memory tool 的区别 有同样表述。与 hooks 架构的呼应契约如何落地AGENTS.md 的契约不是抽象声明而是与具体钩子配置一一对应。以 Claude Code 插件为例hooks/hooks.json 注册了 6 个事件全部通过${CLAUDE_PLUGIN_ROOT}/hooks/claude-hook.sh分发事件matcher职责SessionStartstartup\|resume\|clear\|compact恢复规划上下文Restoring planning contextUserPromptSubmit—每轮注入计划上下文PreToolUseWrite\|Edit\|Bash\|Read\|Glob\|Grep工具调用前注入/提醒PostToolUseWrite\|Edit写操作后进度提醒PreCompact*压缩前刷新进度提醒Stop—完成度闸门Checking planning completion维护者若改动 hooks必须同时保持 hook 结构与 AGENTS.md 契约一致例如契约二无运行时状态意味着 hook 每次触发都从磁盘重新解析计划而不是依赖任何进程内缓存契约三则约束了 memory 层的定位。维护者工作流速查将 AGENTS.md 全文压缩为一份可执行清单合并 PRgh pr view N全文阅读 → 复现 → 供应链审计 → 立即评论确认与修复计划 →python -m pytest tests/ -q绿 →cherry-pick/--rebase合并禁 squash发 release commitCHANGELOG 条目 CONTRIBUTORS.md 更新 README 徽章/releases 表 python scripts/bump-version.py X.Y.Z --dry-run预览后正式 bump打 tag 发布tag 在 release commit 上 → push master tags →gh release create手动分发build-clawhub-upload.py--verify→ 上传 ClawHub.pi/skills/planning-with-files/下npm publishskills.sh 与 marketplace 自动跟随收尾在 PR/Issue 发布含 handle、版本、根因、致谢、SHA 的评论并关闭。这条流水线之所以被写得如此啰嗦正是因为它的每个环节都对应过真实事故v2.40.1 的 squash 归属事故、v2.34.1/v2.36.x 的漏改版本事故、v3.17.0 的 Windows hook 超时事故单次触发 fork 约 130 个进程。AGENTS.md 本质上是这个仓库用事故换来的操作手册——对任何维护者而言先读它再动手就是对这个项目最负责任的做法。【免费下载链接】planning-with-filesPersistent file-based planning for AI coding agents and long-running tasks. Crash-proof markdown plans, session recovery after /clear and compaction, per-turn re-injection against context rot, deterministic completion gate. Manus-style. Install from npm, the Claude Code plugin marketplace, or npx skills. Codex, Cursor, OpenCode, 60 agents.项目地址: https://gitcode.com/GitHub_Trending/pl/planning-with-files创作声明：本文部分内容由AI辅助生成（AIGC），仅供参考