Documentation Updater

Intelligent documentation update workflow to ensure synchronization between code changes and documentation.

Repository Routing

First confirm which repository the changes belong to:

```
ValorVie/custom-skills
```
: Documentation for ai-dev CLI, commands, agents, plugins, project-template, OpenSpec, and framework.
```
ValorVie/ai-dev-skills
```
: First-party skill content, skill tests, collection README, and CHANGELOG.

Cross-repository changes should be checked and submitted separately. Do not copy skill content back to the framework repository, nor place ai-dev runtime files in skill directories to impersonate self-contained content.

Workflow Overview

Phase 1: Change Collection → Phase 2: Change Classification → Phase 3: Documentation Exploration → Phase 4: Impact Analysis → Phase 5: Documentation Update → Phase 6: Verification

Phase 1: Change Collection

Step 1.1: Confirm Analysis Scope

If the user does not specify a scope, use AskUserQuestion to inquire:

Question: How many recent commits would you like to analyze?
Options:
- Recent 1 commit (default)
- Recent 5 commits
- Recent 10 commits
- Custom scope (enter commit hash or branch comparison)

Step 1.2: Collect Change Data

Execute based on user selection:

bash

# 查看最近 N 個 commits
git log --oneline -N

# 查看變更的檔案
git diff --name-only HEAD~N

# 查看詳細變更摘要
git log --stat HEAD~N..HEAD

Alternative (branch comparison):

bash

git diff --name-only main...HEAD
git log --oneline main...HEAD

Step 1.3: Organize Change List

Output format:

markdown

## Change Summary

**Analysis Scope**: HEAD~5..HEAD (5 commits)

### Changed Files
- plugins/ecc-hooks/README.md
- plugins/ecc-hooks/hooks/hooks.json
- openspec/changes/xxx/tasks.md
- ...

### Commit Summary
- abc1234: feat: Add PHP hooks support
- def5678: fix: Fix formatting issues

Phase 2: Change Classification

Step 2.1: Automatically Identify Change Types

Identify change types based on file paths and content:

File Path Pattern	Change Type
`skills/*/.md`	Skill change in `ai-dev-skills` repository
`agents/*/.md`	Agent change
`commands/*/.md`	Command change
`plugins/*/`	Plugin change
`script/*/.py`	CLI feature change
`pyproject.toml` (version)	Version release
`openspec/specs/*/`	Spec change
`upstream/*/`	Upstream integration
`sources/*/`	Resource integration
`docs/*/`	Documentation change (cross-update may be required)
`.standards/*/`	Standard specification change

Step 2.2: Extract Keywords

Extract keywords from changes for subsequent documentation search:

Extract from file names:
```
ecc-hooks
```
→ search keyword
Extract from commit messages:
```
Add PHP hooks
```
→
```
PHP
```
,
```
hooks
```
Extract from added/modified content: function names, class names, feature names

Step 2.3: Output Classification Results

markdown

## Change Classification

| Type | Count | Key Items |
|------|-------|-----------|
| Plugin Change | 3 | ecc-hooks |
| CLI Change | 1 | derive-tests |
| Spec Change | 2 | hook-testing, code-quality-hooks |

**Extracted Keywords**: `ecc-hooks`, `PHP`, `hooks`, `code-quality`, `testing`

Phase 3: Documentation Exploration

Step 3.1: Prioritize Checking Core Documentation

Mandatory files (in priority order):

```
CHANGELOG.md
```
- Version history (required for almost all changes)
```
README.md
```
- Project overview
```
openspec/config.yaml
```
- Project context (legacy version is
```
openspec/project.md
```
, check if exists)
```
docs/**/*.md
```
- Documentation folder

Step 3.2: Search Related Documentation Using Keywords

For each extracted keyword, search for related files in the project:

bash

# 搜尋檔案名稱包含關鍵字
find . -name "*keyword*" -type f

# 搜尋檔案內容包含關鍵字
grep -rl "keyword" --include="*.md" .

# 搜尋 README 文件
find . -name "README.md" -type f

Search using Grep tool:

Search for occurrences of
```
ecc-hooks
```
in all
```
.md
```
files
Search for relevant descriptions of
```
PHP
```
in documentation
Search which files record feature names

Step 3.3: Build Documentation Association Map

markdown

## Documentation Association Analysis

### Keyword: `ecc-hooks`
Found related files:
- `README.md` (Line 599-627: Claude Code Plugin section)
- `plugins/ecc-hooks/README.md` (Main documentation)
- `docs/AI開發環境設定指南.md` (Line 514-541: Plugin installation instructions)
- `CHANGELOG.md` (Line 136-138: Version 0.9.7 record)

### Keyword: `PHP`
Found related files:
- `docs/dev-guide/workflow/CODE-QUALITY-TOOLS.md` (PHP tool installation)
- `plugins/ecc-hooks/README.md` (PHP formatting hooks)

Phase 4: Impact Analysis

Step 4.1: Map Change Types to Documentation

Use the following mapping table to determine which files need updates:

Plugin Changes

File	Update Content	Necessity
`CHANGELOG.md`	Add/modify entries	Required
`plugins/<name>/README.md`	Feature description, installation method	Required
`README.md`	If usage changes are involved	As needed
`docs/AI開發環境設定指南.md`	If installation process is involved	As needed

Skill Changes

File	Update Content	Necessity
`ai-dev-skills/CHANGELOG.md`	Add or modify entries	Required
`ai-dev-skills/README.md`	Skill list, installation method, or boundary	As needed
`custom-skills/upstream/npx-skills.yaml`	Update only when baseline adoption list changes	As needed

Agent Changes

File	Update Content	Necessity
`CHANGELOG.md`	Add entries	Required
`agents/claude/README.md`	Agent list table	Required
`docs/Skill-Command-Agent差異說明.md`	"Appendix: Built-in Agents List"	Required

Command Changes

File	Update Content	Necessity
`CHANGELOG.md`	Add entries	Required
`commands/claude/README.md`	Command list table	Required

CLI Feature Changes

File	Update Content	Necessity
`CHANGELOG.md`	Add/modify entries	Required
`README.md`	Command instructions, parameter tables	Required

Version Release

File	Update Content	Necessity
`pyproject.toml`	Version field	Required
`CHANGELOG.md`	Date, version number	Required
`README.md`	Verify feature descriptions	As needed

Step 4.2: Version Consistency Check

Check if version numbers are consistent in the following locations:

```
pyproject.toml
```
→
```
version
```
```
plugins/<name>/plugin.json
```
→
```
version
```
```
plugins/<name>/package.json
```
→
```
version
```
(if exists)

Step 4.3: Generate Impact Report

markdown

## Impact Analysis Report

### Files Needing Updates

| File | Reason | Priority | Status |
|------|--------|----------|--------|
| `CHANGELOG.md` | Add ecc-hooks testing framework | P1 | ⬜ Pending update |
| `plugins/ecc-hooks/package.json` | Version synchronization (1.0.0 → 1.1.0) | P1 | ⬜ Pending update |
| `README.md` | No feature changes | - | ✅ No update needed |
| `docs/dev-guide/workflow/CODE-QUALITY-TOOLS.md` | No feature changes | - | ✅ No update needed |

### Version Consistency
- `pyproject.toml`: 1.0.4
- `plugins/ecc-hooks/plugin.json`: 1.1.0
- `plugins/ecc-hooks/package.json`: 1.0.0 ⚠️ **Inconsistent**

Phase 5: Documentation Update

Step 5.1: Update Files by Priority

P1 - Required Updates: First handle CHANGELOG.md and version synchronization
P2 - Important Updates: Feature documentation, README
P3 - Optional Updates: Reference documentation, secondary files

Step 5.2: Must Read Before Updating

Important: Before updating any file, you must first use the Read tool to read the file and confirm:

Current content
Position to insert/modify
Format specifications

Step 5.3: Follow Format Specifications

CHANGELOG Format

markdown

## [Unreleased]

### Added
- **Feature Category**
  - Detailed description
  - Sub-item description

### Changed
- **Breaking Change Category**
  - Change description
  - Migration guide

### Fixed
- Fix description

### Removed
- Removal description

Version History Table Format

markdown

## Version History

| Version | Date | Changes |
|---------|------|---------|
| 1.1.0 | 2026-01-28 | Added feature X |

Phase 6: Verification

Step 6.1: Verification Checklist

After completing updates, confirm item by item:

markdown

## Update Verification Checklist

### Documentation Update Status
- [x] `CHANGELOG.md` - Added ecc-hooks testing framework record
- [x] `plugins/ecc-hooks/package.json` - Version synchronized to 1.1.0
- [ ] `README.md` - No update needed

### Version Consistency (After Update)
| Location | Version | Status |
|----------|---------|--------|
| `pyproject.toml` | 1.0.4 | ✓ |
| `plugins/ecc-hooks/plugin.json` | 1.1.0 | ✓ |
| `plugins/ecc-hooks/package.json` | 1.1.0 | ✓ |

### Cross-Reference
- [x] Feature lists are consistent across documents
- [x] Links are valid
- [x] Tables are updated

Step 6.2: Output Final Summary

markdown

## Documentation Update Summary

**Analysis Scope**: HEAD~5..HEAD

### Updated Files
| File | Update Content |
|------|----------------|
| `CHANGELOG.md` | Added ECC Hooks Plugin testing framework record |
| `plugins/ecc-hooks/package.json` | Version synchronized to 1.1.0 |

### No Updates Needed
| File | Reason |
|------|--------|
| `README.md` | No major feature changes |
| `docs/*` | Unrelated to this change |

### Version Consistency
✓ All version numbers are synchronized

Quick Reference

Common Omission Reminders

When Adding an Agent

⚠️
```
docs/Skill-Command-Agent差異說明.md
```
- "Appendix: Built-in Agents List"
⚠️
```
agents/claude/README.md
```
- Built-in Agents table

When Adding a Command Series

⚠️
```
commands/claude/README.md
```
- Need to add complete category sections

When Integrating Upstream

⚠️
```
upstream/README.md
```
- "Integration Decision Record" section

When Changing a Plugin

⚠️ Version number synchronization (plugin.json and package.json)

Language Specifications

All documentation uses Traditional Chinese, with English technical terms retained:

Skill, Command, Agent, Hook, Plugin
CLI, TUI, MCP, API
Git, GitHub, upstream

Parameter Description

This skill accepts the following parameters:

Parameter	Description	Example
No parameter	Ask for analysis scope	`/doc-updater`
`N`	Analyze recent N commits	`/doc-updater 5`
`--since <ref>`	Analyze from specified ref	`/doc-updater --since v1.0.0`
`--check`	Only check, do not perform updates	`/doc-updater --check`

custom-skills-doc-updater

NPX Install

Tags

SKILL.md Content (Chinese)

Documentation Updater

Repository Routing

Workflow Overview

Phase 1: Change Collection

Step 1.1: Confirm Analysis Scope

Step 1.2: Collect Change Data

Step 1.3: Organize Change List

Phase 2: Change Classification

Step 2.1: Automatically Identify Change Types

Step 2.2: Extract Keywords

Step 2.3: Output Classification Results

Phase 3: Documentation Exploration

Step 3.1: Prioritize Checking Core Documentation

Step 3.2: Search Related Documentation Using Keywords

Step 3.3: Build Documentation Association Map

Phase 4: Impact Analysis

Step 4.1: Map Change Types to Documentation

Plugin Changes

Skill Changes

Agent Changes

Command Changes

CLI Feature Changes

Version Release

Step 4.2: Version Consistency Check

Step 4.3: Generate Impact Report

Phase 5: Documentation Update

Step 5.1: Update Files by Priority

Step 5.2: Must Read Before Updating

Step 5.3: Follow Format Specifications

CHANGELOG Format

Version History Table Format

Phase 6: Verification

Step 6.1: Verification Checklist

Step 6.2: Output Final Summary

Quick Reference

Common Omission Reminders

When Adding an Agent

When Adding a Command Series

When Integrating Upstream

When Changing a Plugin

Language Specifications

Parameter Description