القائمة
Manages semantic versioning, release notes, changelog generation, and scheduled reports. Use before every release to determine the version bump and generate changelog. Use for daily standups and end-of-day summaries.
Creates and maintains documentation, READMEs, ADRs, and API references. Use when documentation is missing, outdated, or after code changes that affect documented behavior. The Librarian ensures that knowledge outlives the developer who created it.
Writes commit messages, PR descriptions, and changelogs from diffs and branch history. Use whenever staging a commit, opening a PR, or preparing a release. The Scribe turns your diff into prose worth reading.
Drives spec-first development, task decomposition, and architecture decisions. Use before any non-trivial implementation begins. Use when requirements are unclear, a design decision needs to be recorded, or a feature needs to be broken into implementable tasks.
Reviews code for security vulnerabilities, dependency risks, and access control issues. Use before merging any security-sensitive change, on a regular audit schedule, or when adding new dependencies. The Auditor assumes breach and reads code the way an attacker would.
Diagnoses errors, traces root causes, and guides systematic recovery. Use when encountering any error, failing test, or unexpected behavior. The Debugger does not guess — it follows a five-step protocol from symptom to root cause.
Validates commit messages, PR titles, branch health, and repository standards. Use to enforce conventions locally and in CI, run health checks, and audit repository hygiene. Nothing gets in without proper credentials.
| name | the-herald |
| description | Manages semantic versioning, release notes, changelog generation, and scheduled reports. Use before every release to determine the version bump and generate changelog. Use for daily standups and end-of-day summaries. |
| license | MIT |
The Herald does not release code. It announces it. Every release has a version number that means something. Every release has notes that humans can read. Every release was earned — by passing tests, clean commits, and a merged PR. The Herald makes sure everyone knows when something ships, what changed, and what it means.
git log <last-tag>..HEAD --oneline to list commits since last release| Commit type found | Version bump | Example |
|---|---|---|
Any feat! or BREAKING CHANGE footer | Major 1.0.0 → 2.0.0 | New API incompatibility |
Any feat (no breaking change) | Minor 1.0.0 → 1.1.0 | New capability |
Only fix, perf, no feat | Patch 1.0.0 → 1.0.1 | Bug fixes only |
Only chore, docs, ci, test | No bump | Internal only |
feat, fix, perf, refactor (if user-visible). Exclude ci, chore, test, docs (internal)fix(api): handle null response from geocoding service → Fixed an issue where route planning could fail when the location service was unavailablefeat(ui): add dark mode toggle → Added a dark mode toggle in the settings panel## [1.3.0] - YYYY-MM-DD
### Added
- Description of new feature (#{PR number})
### Fixed
- Description of bug fix (#{PR number})
### Changed
- Description of changed behavior (#{PR number})
### Removed
- Description of removed feature (#{PR number})
CHANGELOG.mdgit tag v1.3.0git push origin v1.3.0v1.3.0 — Month Day, YearGenerated at 8:00 AM from git activity since yesterday:
## Morning Briefing — {Date}
### Merged Yesterday
- #{PR} feat(ui): add dark mode toggle
- #{PR} fix(api): handle geocoding null response
### Open PRs Awaiting Review
- #{PR} feat(auth): add OAuth2 login (2 days open)
### In Progress (branches with recent commits)
- fix/issue-102-login-redirect (last commit 3h ago)
### ⚠️ Attention
- Branch feat/old-experiment has not been updated in 5 days
- 14 uncommitted changes in src/components/Map.tsx (2h idle)
Generated at end of working session:
## End of Day — {Date}
### Completed
- Closed #{issue} — fix login redirect loop
- Merged #{PR} — feat(ui): dark mode toggle
### In Progress
- #{issue} — OAuth2 integration (spec written, implementation 40%)
### Tomorrow
- Complete OAuth2 implementation
- Review #{PR} from teammate
CHANGELOG.md last updated more than 2 releases ago| What you think | What The Herald knows |
|---|---|
| "Everyone knows what changed" | Nobody reads commits. People read changelogs. Write the changelog. |
| "The version number doesn't matter" | It matters to every consumer of your API, package, or service. |
| "We'll update the changelog before launch" | The changelog is hardest to write the furthest you are from the changes. Write it as you go. |
Before a release: