docs/spec/ と README.md / README.ja.md A skill to synchronize in accordance with the current state of the implementation.
Role
Detect and update cases where implementation is ahead and documentation has not caught up.
As a basis for judgment, use git log と .team/tasks/ closed tasks.
There are broadly 3 categories of targets:
docs/spec/*.md— Integrated specification (the "what" and "why" of the implementation)README.md/README.ja.md— User-facing installation and getting-started guide (English-Japanese bilingual)skills/cmux-team-guide/SKILL.md— User-facing help and reference (CLI command list, TUI, troubleshooting)
Synchronization procedure
1. Check the last updated time of docs/spec/
git log -1 --format="%H %ai %s" -- docs/spec/
→ <base_hash> と <last_updated> Record
2. Collect implementation changes since then
# ベースハッシュ以降のコミット（実装ファイルに絞る）
git log --oneline <base_hash>..HEAD -- skills/ commands/ bin/ package.json .claude-plugin/
3. Supplement with closed tasks
# closed タスクの一覧（タイトルと本文で何が実装されたか把握）
cat .team/task-state.json | python3 -c "
import json, sys
data = json.load(sys.stdin)
for tid, info in data.items():
if info.get('status') == 'closed':
print(tid, info.get('title',''))
"
For commits whose changes are ambiguous, read the corresponding task file (.team/tasks/Txxx-*.md) to supplement.
4. Cross-check with docs/spec/ and README
Target files:
| File | Content |
|---|---|
docs/spec/00-project-overview.md |
Project overview and architecture |
docs/spec/01-skill-cmux-team.md |
cmux-team skill specification |
docs/spec/02-skill-cmux-agent-role.md |
cmux-agent-role skill specification |
docs/spec/03-commands.md |
Slash command definitions |
docs/spec/04-templates.md |
Agent template specification |
docs/spec/05-install-and-infrastructure.md |
Installation and infrastructure configuration |
docs/spec/06-implementation-tasks.md |
Implementation task definitions |
README.md |
User-facing getting-started guide (English) |
README.ja.md |
User-facing getting-started guide (Japanese) |
skills/cmux-team-guide/SKILL.md |
User-facing help and reference |
Read each file and cross-check it against the collected changes to detect discrepancies. For the README, especially focus on checking whether the CLI command list, installation procedure, and feature list match the implementation. Maintain the bilingual relationship between English and Japanese.skills/cmux-team-guide/SKILL.md Check whether the CLI command list, layout description, TUI keyboard shortcuts, and troubleshooting match the implementation.
5. Update or output a diff report
The behavior differs depending on the mode:
| Mode | Behavior |
|---|---|
--dry-run |
Output a diff report only. Do not change files |
| (Default) | Present the diff to the user and update after confirmation |
--auto |
Automatically update without confirmation |
Format of the diff report:
## docs/spec/ 同期レポート
最終更新: <last_updated>
対象コミット: N件
対象 closed タスク: N件
### 更新が必要なファイル
#### docs/spec/03-commands.md
- `/docs-sync` コマンドの追加（T098）
- `master.md` の「タスクへの補足・追加指示」セクション追加（T097相当）
#### docs/spec/04-templates.md
- `dockeeper.md` テンプレートの役割説明を更新
### 変更不要なファイル
- 00-project-overview.md — 変更なし
- 01-skill-cmux-team.md — 変更なし
Notes
docs/spec/is a "specification synchronized with the implementation". Do not write internal implementation detailsREADME.md/README.ja.mdis the "document that users read first". Do not include internal specifications for developers- The English and Japanese READMEs should have matching section structures, headings, and description order (maintain the bilingual relationship)
- Remove descriptions of deleted files and features
- Maintain the existing writing style and structure (do not perform major reformatting)
- Do not write unknown changes based on guesswork; instead, record them in the diff report as 'needs confirmation'.