README Updater

Analyze project structure, check README completeness, and provide updates.

Workflow

1. Analyze project structure - Determine if monorepo or single project
2. Collect project info - Read configs, docs, and code structure
3. Analyze existing README - Check against standard sections
4. Check sub-packages - For monorepos, verify each package's README
5. Generate report - List missing/outdated sections
6. Apply updates - After user confirmation

Project Analysis

Detect Monorepo

Check for:

• packages/ or apps/ directories
• workspaces field in package.json
• lerna.json or pnpm-workspace.yaml

Collect Information

| Source | Extract | |--------|---------| | package.json / pyproject.toml | Name, description, version | | docs/ directory | Architecture, API docs, guides | | Code structure | Main directories, core modules, entry points | | Sub-packages | Names, purposes, dependencies, README status |

README Standard Sections

Required

• Title & Introduction - Clear name, one-line description, badges
• Features - Main functionality, advantages
• Installation - Requirements, steps, dependencies
• Usage - Basic examples, common use cases
• API Documentation - Main APIs or links to docs
• Configuration - Options, environment variables, examples

Recommended

• Development - Setup, build/test commands
• Contributing - How to contribute, code standards, PR workflow
• License
• Changelog - Or link to CHANGELOG.md
• FAQ
• Related Resources

Monorepo Handling

Root README

• Explain overall project architecture
• List all sub-packages with purposes
• Provide monorepo development guide
• Describe package dependencies

Sub-package README

Each should include:

• Package name and purpose
• Installation (from monorepo or standalone)
• Usage examples
• API docs or links
• Relationships with other packages

docs Directory Integration

If docs/ exists:

1. README should contain overview & quick start
2. Link to detailed docs for in-depth content
3. Avoid duplication

Example documentation section:

markdown
## Documentation

- [Architecture](./docs/architecture.md)
- [API Reference](./docs/api.md)
- [Configuration Guide](./docs/configuration.md)

Output Format

Generate analysis report:

markdown
# README Analysis Report

## Project Type
- [x] Monorepo / [ ] Single Project

## Root README Status

### ✓ Complete
- Title & Introduction
- Features

### ✗ Missing or Outdated
- Installation (version outdated)
- Sub-packages list (missing)

## Sub-Packages Status

| Package | README Exists | Completeness | Issues |
|---------|---------------|--------------|--------|
| @scope/core | ✓ | 90% | Missing config section |
| @scope/utils | ✓ | 60% | Missing usage examples |
| @scope/cli | ✗ | 0% | README not found |

## Suggested Updates

### 1. Add Project Architecture Section
[Example content...]

## docs Directory

- `docs/architecture.md` - Architecture overview
- `docs/api.md` - API documentation

Recommend adding documentation index to README.

Critical Constraints

• Consistency - All READMEs use same format style
• Traditional Chinese - Use Taiwan terminology for descriptions
• Key terms - Add English in parentheses for clarity: 快取 (Cache)
• Code examples - Keep original language, add bilingual comments
• Link validity - Ensure internal links point to correct files
• Version info - Match version numbers with package.json
• Avoid duplication - Link to docs instead of repeating content

Generic Sections Constraint

不主動添加的章節

當 README 中不存在以下概念時，除非使用者明確要求，否則不應寫入：

• ## author - 作者資訊
• ## 相容性 - Compatibility（如 Node.js 版本要求）
• ## 貢獻 - Contributing（如 "歡迎提交 Issue 和 Pull Request!"）
• ## 授權 - License（如 "ISC License"）

判斷邏輯

檢查現有 README
    │
    ▼
該章節是否存在？
    │
    ├─ 是 → 保留原有內容，可選擇性更新
    │
    └─ 否 → 不主動添加，除非使用者明確要求

範例

markdown
# 錯誤示範（不應主動添加）

## author
John Doe

## 相容性
- Node.js >= 12

## 貢獻
歡迎提交 Issue 和 Pull Request！

## 授權
ISC License

markdown
# 正確做法

若使用者要求更新 README：
- 先分析現有內容
- 僅補充缺少的核心章節（如 Installation、Usage）
- 不添加上述通用章節，除非明確要求

Example Workflow

User: Update README

1. Analyze structure → Monorepo detected (packages/ exists)
2. Collect info → Read package.json, scan docs/, list packages
3. Analyze root README → Missing architecture section, outdated installation
4. Check sub-packages → core: complete, utils: missing examples, cli: no README
5. Provide suggestions → List needed content with examples
6. Execute updates → After user confirmation