update-docs

Compare original and translation side by side

🇺🇸

Original

English

🇨🇳

Translation

Chinese

GM UPDATE-DOCS — Documentation Refresh

GM UPDATE-DOCS — 文档更新

You are in the UPDATE-DOCS phase. Feature work is verified and pushed. Refresh all documentation to match the actual codebase state right now.

GRAPH POSITION:

PLAN → EXECUTE → EMIT → VERIFY → [UPDATE-DOCS] → COMPLETE

Entry: Feature work verified, committed, and pushed. Entered from
```
gm-complete
```
.

你正处于UPDATE-DOCS阶段。功能开发已验证并推送。更新所有文档以匹配当前代码库的实际状态。

GRAPH POSITION:

PLAN → EXECUTE → EMIT → VERIFY → [UPDATE-DOCS] → COMPLETE

进入条件: 功能开发已验证、提交并推送。从
```
gm-complete
```
进入。

TRANSITIONS

流转规则

FORWARD: All docs updated, committed, and pushed → COMPLETE (session ends)

BACKWARD:

Diff reveals unknown architecture change → invoke
```
planning
```
skill, restart chain
Doc write fails post-emit verify → fix and re-verify before advancing

向前流转: 所有文档已更新、提交并推送 → COMPLETE（会话结束）

向后流转:

差异分析揭示未知架构变更 → 调用
```
planning
```
技能，重启流程链
文档编写在EMIT验证后失败 → 修复并重新验证后再推进

EXECUTION SEQUENCE

执行步骤

Step 1 — Understand what changed:

exec:bash
git log -5 --oneline
git diff HEAD~1 --stat

Witness which files changed. Identify doc-sensitive changes: new skills, new states in the state machine, new platforms, modified architecture, new constraints, renamed files.

Step 2 — Read current docs:

exec:nodejs
const fs = require('fs');
['README.md', 'CLAUDE.md', 'docs/index.html',
 'plugforge-starter/agents/gm.md'].forEach(f => {
  try { console.log(`=== ${f} ===\n` + fs.readFileSync(f, 'utf8')); }
  catch(e) { console.log(`MISSING: ${f}`); }
});

Identify every section that no longer matches the actual codebase state.

Step 3 — Write updated docs:

Write only sections that changed. Do not rewrite unchanged content. Rules per file:

README.md: platform count matches adapters in

platforms/

, skill tree diagram matches current state machine, quick start commands work.

CLAUDE.md: Only non-obvious technical caveats that required multiple runs to discover — things that could not be known without hitting the problem first. Remove anything that no longer applies. Never add anything obvious from reading the code or that any developer would already know. The test: "would a developer need to discover this the hard way, or is it self-evident?" If self-evident, exclude it.

docs/index.html:

PHASES

array matches current skill state machine phases. Platform lists match

platforms/

directory. State machine diagram updated if new phases added.

plugforge-starter/agents/gm.md: Skill chain on the

gm skill →

line updated if new skills were added.

exec:nodejs
const fs = require('fs');
fs.writeFileSync('/abs/path/file.md', updatedContent);

Step 4 — Verify from disk:

exec:nodejs
const fs = require('fs');
const content = fs.readFileSync('/abs/path/file.md', 'utf8');
console.log(content.includes('expectedString'), content.length);

Witness each written file from disk. Any variance from expected content → fix and re-verify.

Step 5 — Commit and push:

exec:bash
git add README.md CLAUDE.md docs/index.html plugforge-starter/agents/gm.md
git diff --cached --stat

Witness staged files. Then commit and push:

exec:bash
git commit -m "docs: update documentation to reflect session changes"
git push -u origin HEAD

Witness push confirmation. Zero variance = COMPLETE.

步骤1 — 了解变更内容:

exec:bash
git log -5 --oneline
git diff HEAD~1 --stat

查看哪些文件发生了变更。识别对文档有影响的变更：新技能、状态机中的新状态、新平台、修改后的架构、新约束、重命名的文件。

步骤2 — 读取当前文档:

exec:nodejs
const fs = require('fs');
['README.md', 'CLAUDE.md', 'docs/index.html',
 'plugforge-starter/agents/gm.md'].forEach(f => {
  try { console.log(`=== ${f} ===\n` + fs.readFileSync(f, 'utf8')); }
  catch(e) { console.log(`MISSING: ${f}`); }
});

识别所有与当前代码库状态不符的章节。

步骤3 — 编写更新后的文档:

仅编写发生变更的章节。不要重写未变更的内容。各文件规则：

README.md: 平台数量与

platforms/

中的适配器数量一致，技能树图与当前状态机匹配，快速启动命令可正常运行。

CLAUDE.md: 仅保留那些需要多次尝试才能发现的非显而易见的技术注意事项——即不遇到问题就无法知晓的内容。移除不再适用的内容。切勿添加从代码中可直接读取的明显信息，或任何开发者本应知晓的内容。测试标准：“开发者是否需要通过碰壁才能发现这一点，还是它不言自明？”如果是不言自明的，就排除它。

docs/index.html:

PHASES

数组与当前技能状态机的阶段匹配。平台列表与

platforms/

目录一致。如果添加了新阶段，需更新状态机图。

plugforge-starter/agents/gm.md: 如果添加了新技能，需更新

gm skill →

行中的技能链。

exec:nodejs
const fs = require('fs');
fs.writeFileSync('/abs/path/file.md', updatedContent);

步骤4 — 从磁盘验证:

exec:nodejs
const fs = require('fs');
const content = fs.readFileSync('/abs/path/file.md', 'utf8');
console.log(content.includes('expectedString'), content.length);

从磁盘查看每个已编写的文件。如果与预期内容有任何差异 → 修复并重新验证。

步骤5 — 提交并推送:

exec:bash
git add README.md CLAUDE.md docs/index.html plugforge-starter/agents/gm.md
git diff --cached --stat

查看暂存的文件。然后提交并推送：

exec:bash
git commit -m "docs: update documentation to reflect session changes"
git push -u origin HEAD

查看推送确认信息。无任何差异 = COMPLETE。

DOC FIDELITY RULES

文档保真规则

Every claim in docs must be verifiable against disk right now:

State machine phase names must match skill file
```
name:
```
frontmatter
Platform names must match adapter class names in
```
platforms/
```
File paths must exist on disk
Constraint counts must match actual constraints

If a doc section cannot be verified against disk: remove it, do not speculate.

文档中的每一项声明都必须能立即通过磁盘内容验证：

状态机阶段名称必须与技能文件的
```
name:
```
前置元数据匹配
平台名称必须与
```
platforms/
```
中的适配器类名匹配
文件路径必须在磁盘上存在
约束数量必须与实际约束一致

如果文档的某个章节无法通过磁盘内容验证：移除它，不要猜测。

CONSTRAINTS

约束条件

Never: skip diff analysis | write docs from memory alone | push without verifying from disk | add comments to doc content | claim done without witnessed push output

Always: witness git diff first | read current file before overwriting | verify each file from disk after write | push doc changes | confirm with witnessed push output

→ COMPLETE: Docs committed and pushed → session ends. ↩ SNAKE to PLAN: New unknown about codebase state → invoke

planning

skill.

禁止: 跳过差异分析 | 仅凭记忆编写文档 | 未从磁盘验证就推送 | 向文档内容添加注释 | 未查看推送输出就声称完成

必须: 先查看git差异 | 覆盖前先读取当前文件 | 编写后从磁盘验证每个文件 | 推送文档变更 | 通过查看推送输出确认

→ COMPLETE: 文档已提交并推送 → 会话结束。 ↩ 返回PLAN: 关于代码库状态出现新的未知情况 → 调用

planning

技能。