AGENT SKILL

dh-semver

Apply strict Semantic Versioning — analyze commits since the last tag to determine the bump type (major/minor/patch from conventional commit prefixes), generate an automated changelog grouped by breaking changes, features, fixes, and chores, and create a git tag locally without pushing until confirmed, handling both conventional commits and manual version decisions. Use when preparing a release, invoked by dh-execute-plan after plan completion and dh-final-review for release readiness, or when the user asks "what version is next?", "bump version", "generate changelog", "tag release", or "what changed since last release?".

License 许可
MIT
最近更新
2026-11-10
Stars
★ 8
Forks
1

01 前言 Front Matter

name
dh-semver
license
MIT
metadata
{ "audience": "developers", "workflow": "development" }
description
Apply strict Semantic Versioning — analyze commits since the last tag to determine the bump type (major/minor/patch from conventional commit prefixes), generate an automated changelog grouped by breaking changes, features, fixes, and chores, and create a git tag locally without pushing until confirmed, handling both conventional commits and manual version decisions. Use when preparing a release, invoked by dh-execute-plan after plan completion and dh-final-review for release readiness, or when the user asks "what version is next?", "bump version", "generate changelog", "tag release", or "what changed since last release?".
allowed-tools
bash, read
compatibility
opencode

03 SKILL.md 正文

Harness-localized adaptation of the global semver skill. The versioning algorithm is identical; the harness adaptations are that every git command runs through the dh-execute-cli skill, and this skill is invoked from the bundled loop skills or a direct user request — the harness bundles no commands.

Core Rules

  • Find the last tag: git describe --tags --abbrev=0. If that fails because the repo has no tags yet, default to v0.0.0.
  • Collect the commits since that tag: git log <tag>..HEAD --oneline.
  • Map commit messages to the bump type using conventional commit prefixes:
    • BREAKING CHANGE: in the message body, or ! after the type (feat!:), → MAJOR bump
    • feat: or feat(scope): → MINOR bump
    • fix:, chore:, docs:, style:, refactor:, perf:, test:, ci:, build: → PATCH bump
  • If no conventional commit format is detected, prompt the user for the bump type — never guess.
  • Generate the changelog grouped by Breaking Changes (if any), Features, Fixes, and Chores & Maintenance; every entry keeps its short commit hash.
  • Create the tag locally: git tag -a v<major>.<minor>.<patch> -m "Release v<major>.<minor>.<patch>".
  • Do NOT push the tag — the user confirms before pushing.
  • Run ALL git commands through the dh-execute-cli skill — never run bash directly from the agent applying this skill.

Edge Cases

  • No commits since the last tag → report "No changes — no version bump needed" and stop.
  • No tags in the repo → treat v0.0.0 as the current version, but note it is not a real ref to diff against — enumerate ALL commits with git log --oneline to determine the first release.
  • Tags exist but are unreachable from the current branch (e.g. releases are tagged on main while you work on develop) → git describe under-reports the current version. Cross-check git tag --sort=-v:refname for the highest released tag and state the assumption; the durable fix is the repo's back-merge of main after tagging, which keeps tags reachable.
  • History without conventional commit prefixes → ask the user which bump applies; do not infer a bump from vague messages.

Harness Invocation Sources

The harness bundles no commands, so there is no release command step to import. This skill runs when:

  • dh-execute-plan finishes a plan on a software project and needs the next version bump.
  • dh-final-review checks release readiness and reports the recommended bump.
  • The user asks directly: "what version is next?", "bump version", "generate changelog", "tag release", or "what changed since last release?".

Output Template

# Version Decision

**Current:** vX.Y.Z (tag: <tagname>)
**Bump:** MAJOR / MINOR / PATCH → **vX.Y.Z**
**Reason:** [N breaking changes, N features, N fixes]

# Changelog vX.Y.Z

## Breaking Changes
- [Description] (<commit-short-hash>)

## Features
- [Description] (<commit-short-hash>)

## Fixes
- [Description] (<commit-short-hash>)

## Chores & Maintenance
- [Description] (<commit-short-hash>)

**Tag:** `vX.Y.Z` (created locally — awaiting confirmation to push)

Safety

  • Do not push tags or commits without explicit user confirmation.
  • Do not delete or modify existing tags.
  • Create the tag only after the version decision and changelog are reported; the tag stays local until the user confirms pushing.
  • Report the decision with its git evidence (last tag, commit counts, short hashes) exactly as the dh-execute-cli skill reports it — no guessing.

References

  • dh-execute-plan and dh-final-review skills: the bundled loop steps that invoke this skill.
  • AGENTS.md versioning note: tags are semver on main only.

Doc search

Documentation management: delegate create / update / delete / retrieve of generated documents (excluding docs/plans) to the best available documentation agent (bundled documentation capability as fallback) — the main and only documentation owner (see dh-create-documentation).

Search generated documentation quickly: notesmd-cli search-content "<term>" --vault "<project-name>" or obsidian search query="<term>" (fallback: rg --glob '*.md' "<term>" docs/).

04 同仓库更多 Skills

andrescevp
andrescevp/development-harness

dh-simplify

Review changed code for reuse, quality, and efficiency (three parallel reviews), then fix findings directly. Use after making changes or when asked to clean up, refactor, simplify, or improve this code.

★ 8
andrescevp
andrescevp/development-harness

dh-setup

Audit system software, configure user MCPs/plugins, scaffold project QA (hooks + per-stack tools), bootstrap docs/architecture with the selected architecture agent, and write harness directives into AGENTS.md. Use to check requirements or setup the environment.

★ 8
andrescevp
andrescevp/development-harness

dh-review

Verify a plan sub-task against acceptance criteria, scope, done-when; review diff, validation, regression risk; structured verdict to tasks/review.md. Plan Alignment Mode (fast execution) is a separate mode: no sub-task selection, no diff review, no code review — it compares plan.md with plan_fast.md and writes tasks/review-fast.md (pre-execution) or tasks/review-fast-final.md (plan-end). Use after implementation, to review/verify the sub-task, or to check fast-plan alignment.

★ 8
andrescevp
andrescevp/development-harness

dh-resume-plan

Resume a paused phased plan from docs/plans/<slug>/handoff.md: validate the contract, detect drift, rehydrate context, mark the handoff resumed, and continue via dh-execute-plan resume mode. Use when the user says "resume the plan", "continue where we stopped", "pick up the plan", or "resume after a pause".

★ 8
andrescevp
andrescevp/development-harness

dh-preflight

Run tests, linters, static analysis as a release gate: auto-detect tooling, check dirty state, pass/fail verdict with actionable failures (no auto-fixes). Use to run preflight, pre-release check, or validate before release.

★ 8
andrescevp
andrescevp/development-harness

dh-planning

Write phased plans to ./docs/plans/<slug>/plan.md: phases with sub-tasks, requirements mapping (stable IDs), scope, acceptance criteria. SDD gate: invoke dh-grill-sdd when ./docs/plans/<slug>/sdd.md is absent. Use to plan this or create a plan.

★ 8