diff --git a/CHANGELOG.md b/CHANGELOG.md index db1061f..0fb1fcc 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -6,6 +6,30 @@ The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), ## [Unreleased] +## [0.3.3] - 2026-03-25 + +This is a patch release focused on strengthening all git workflow skills with concrete eval contracts, enhanced validator enforcement, and comprehensive documentation alignment across the skill suite. Evaluations now cover semantic intent classification, emoji/prefix consistency, bot identity handling, and cross-runner compatibility. The pending-worktree confirmation checkpoint in `git-keep-a-changelog` is now explicitly mandatory for concrete releases, with documentation and validator enforcement to prevent bypass. Compare-link footer maintenance is now explicitly required for both changelog create and update paths, with validator assertions and eval coverage. + +### Changed + +- Tightened `git-visual-commits` classification and grouping guidance so same-round edits do not collapse into one umbrella commit and release-adjacent work is split by purpose and audience, +- Clarified `git-visual-commits` prefix behavior to default to emoji-first subjects with no prefix, and only allow emoji plus conventional-commit prefix combos when the user explicitly requests that form, +- Hardened `git-visual-commits` bot-commit execution guidance to prefer direct git paths, fail fast when wrapper tools cannot honor aliases, and recover conservatively after wrong-author attempts, +- Refined `git-visual-commits` and `git-visual-squash-summary` skill descriptions and critical rules for consistency and clarity around semantic intent, identity modes, and reference documentation, +- Reorganized `git-visual-commits`, `git-visual-squash-summary`, and `git-keep-a-changelog` skills with explicit workflow steps, clarified parameter forms, and synchronized emoji/prefix reference contract, +- Enhanced `skill-creator-agnostic` for eval directory structure, Codex CLI Windows benchmarking, and runner-agnostic parity validation, +- Clarified `git-keep-a-changelog` pending-worktree confirmation gate as mandatory for concrete releases with new "Mandatory Checkpoints" and "User Intent vs. Mandatory Gates" sections that distinguish between optional scope refinements and required safety checkpoints, +- Strengthened `git-keep-a-changelog` compare-link footer rules to explicitly document insertion, verification, and repair on every edit path. + +### Fixed + +- Extended `validate-skill-templates.ps1` to enforce release-adjacent grouping rules, direct git execution guidance, fail-fast tool-path checks, non-destructive recovery rules, refined prefix behavior, and commit-language consistency across all git skills, +- Updated the README skill summary so the published repo guidance reflects stronger semantic grouping, direct bot-path execution, conservative commit-repair workflow, clarified prefix defaults, and updated skill entry documentation, +- Added concrete eval contracts with test cases for all git workflow skills: `git-visual-commits` (six tests), `git-visual-squash-summary` (five tests), and `git-keep-a-changelog` (six tests, including pending-worktree gate bypass validation), covering plan review, identity handling, emoji/prefix preservation, SemVer classification, prose wrapping, and consistency validation, +- Added per-skill eval coverage for `markdown-illustrator` and strengthened `skill-creator-agnostic` with benchmark contract reference and Windows PowerShell benchmarking guidance, +- Hardened skill-template validators to enforce the mandatory pending-worktree gate documentation in `git-keep-a-changelog`, requiring SKILL.md sections on mandatory checkpoints, FORMS.md gate emphasis, and evals.json test expectations for gate enforcement, +- Extended validator assertions for `git-keep-a-changelog` to enforce compare-link footer documentation and require eval test case for missing-footer insertion behavior. + ## [0.3.2] - 2026-03-23 This is a minor release introducing the markdown-illustrator skill for visualization-first document analysis, with expanded repository branding, comprehensive skill documentation, and foundational eval fixture file infrastructure across the skill suite. @@ -102,7 +126,8 @@ This is a minor release that introduces two complementary git workflow skills, e - Improved scaffold fidelity with hidden `.bot` asset preservation, explicit UTF-8 and BOM handling, and checks aimed at preventing mojibake or incomplete generated output. -[Unreleased]: https://github.com/codebeltnet/agentic/compare/v0.3.2...HEAD +[Unreleased]: https://github.com/codebeltnet/agentic/compare/v0.3.3...HEAD +[0.3.3]: https://github.com/codebeltnet/agentic/compare/v0.3.2...v0.3.3 [0.3.2]: https://github.com/codebeltnet/agentic/compare/v0.3.1...v0.3.2 [0.3.1]: https://github.com/codebeltnet/agentic/compare/v0.3.0...v0.3.1 [0.3.0]: https://github.com/codebeltnet/agentic/compare/v0.2.0...v0.3.0 diff --git a/README.md b/README.md index 9475d6c..11fec42 100644 --- a/README.md +++ b/README.md @@ -12,7 +12,7 @@ One repo-wide convention matters especially for scaffolding skills: prefer dynam Another repo rule is intentionally strict: every repo-managed skill ships with its own `evals/evals.json`, and those evals are run per skill from a temp workspace instead of from inside this repository. -Another part of that workflow is now mandatory too: when a repo-managed skill is created or modified, the author must run both `with_skill` and `without_skill` comparison executions from a temp workspace, aggregate the results into `benchmark.json`, and open `eval-viewer/generate_review.py` from the installed Anthropic `skill-creator` copy, typically under `~/.agents/skills/skill-creator/` or `~/.claude/skills/skill-creator/`, so a human can review both the `Outputs` and `Benchmark` views before sign-off. For new skills the baseline is `without_skill`; for existing skills it can be `without_skill` or the previous/original skill version, matching the `skill-creator` benchmark flow. +Another part of that workflow is now mandatory too: when a repo-managed skill is created or modified, the author must run both `with_skill` and `without_skill` comparison executions from a temp workspace, aggregate the results into `benchmark.json`, and open `eval-viewer/generate_review.py` from the installed Anthropic `skill-creator` copy, typically under `~/.agents/skills/skill-creator/` or `~/.claude/skills/skill-creator/`, so a human can review both the `Outputs` and `Benchmark` views before sign-off. For new skills the baseline is `without_skill`; for existing skills it can be `without_skill` or the previous/original skill version, matching the `skill-creator` benchmark flow. When the available runner supports sub-agents or equivalent background tasks, the measured benchmark should fan out paired executor runs in parallel and parallelize independent grading work too, rather than running evals serially by habit. One more consistency rule matters for form-driven skills: native input fields are treated as a host feature, not something a model can rely on. Skills in this repo must stay usable with or without UI widgets, and must fall back to the same deterministic one-field-at-a-time flow when the host only supports plain chat. @@ -72,11 +72,11 @@ npx skills add https://github.com/codebeltnet/agentic --skill dotnet-strong-name | Skill | Description | |-------|-------------| -| [git-visual-commits](skills/git-visual-commits/SKILL.md) | AI-driven git commit workflow with emoji (gitmoji-first), conventional prefixes, and three identity modes: bot-attributed (`git bot commit`), human-attributed (`git commit`), and collaborative (`git our commit` — agent analyzes authorship, human picks attribution). Includes commit body by default (opt out with `no-body`), semantic intent splitting, and auto-approval mode (`yolo` / `auto`). The agent does all the work either way. Stack-agnostic. | -| [git-keep-a-changelog](skills/git-keep-a-changelog/SKILL.md) | Git-aware Keep a Changelog companion that creates or updates `CHANGELOG.md` from the current branch by default. Reads full commit subjects and bodies plus the net diff, infers a release heading from a branch version hint like `v0.3.0/...` when available, creates a compliant changelog if the file does not exist yet, writes a required SemVer-aware release highlight, preserves natural prose wrapping, and curates `Added` / `Changed` / `Fixed` style sections instead of dumping raw commit logs. | +| [git-visual-commits](skills/git-visual-commits/SKILL.md) | AI-driven git commit workflow with emoji-first subjects (gitmoji-first), optional conventional prefixes only on explicit request, and three identity modes: bot-attributed (`git bot commit`), human-attributed (`git commit`), and collaborative (`git our commit` — agent analyzes authorship, human picks attribution). Includes commit body by default (opt out with `no-body`), semantic intent splitting, bundled `commit-language.md` validation from the skill resource path rather than repo-root guesses, clarification-before-correction safety, and auto-approval mode (`yolo` / `auto`). The agent does all the work either way. Stack-agnostic. | +| [git-keep-a-changelog](skills/git-keep-a-changelog/SKILL.md) | Git-aware Keep a Changelog companion that creates or updates `CHANGELOG.md` from the current branch by default. Reads full commit subjects and bodies plus the net diff, infers a release heading from a branch version hint like `v0.3.0/...` when available, must ask a mandatory `Yes / No / Custom` confirmation question before including pending staged, unstaged, or untracked worktree changes in a concrete release draft, now backed by `FORMS.md` so compatible hosts can render a native choice UI while preserving the same text fallback, creates a compliant changelog if the file does not exist yet, writes a required SemVer-aware release highlight, maintains or inserts the Keep a Changelog compare-link footer on both create and update paths, preserves natural prose wrapping, and curates `Added` / `Changed` / `Fixed` style sections instead of dumping raw commit logs. | | [git-nuget-release-notes](skills/git-nuget-release-notes/SKILL.md) | Git-aware NuGet release-notes companion for .NET repos that keep cumulative `.nuget/{ProjectName}/PackageReleaseNotes.txt` files. Discovers packable `src/` projects, resolves concrete package version and availability, creates missing files when needed, and writes per-package `ALM` / `Breaking Changes` / `New Features` / `Improvements` / `Bug Fixes` style notes from full commit context plus the net diff instead of dumping commit subjects. | | [git-nuget-readme](skills/git-nuget-readme/SKILL.md) | Git-aware NuGet README companion for .NET repos that advertise a package from `src/`. Resolves the real packable project the README should sell, combines git history with actual package metadata, source capabilities, and relevant tests when feasible, preserves honest badge/docs/contributing sections, and writes a forthcoming, adoption-friendly `README.md` with repo-derived branding, clear value, install, framework-support, and quick-start guidance. | -| [git-visual-squash-summary](skills/git-visual-squash-summary/SKILL.md) | Non-mutating grouped-summary companion to `git-visual-commits`. Turns noisy commit stacks into a curated set of compact summary lines for PR or squash contexts, preserving technical identifiers, merging overlap, dropping low-signal noise, highlighting distinct meaningful efforts, and avoiding changelog-style wording or unsupported claims. | +| [git-visual-squash-summary](skills/git-visual-squash-summary/SKILL.md) | Non-mutating grouped-summary companion to `git-visual-commits`. Turns the full current feature branch into a curated set of compact summary lines for PR or squash-and-merge contexts by default, preserving technical identifiers, merging overlap, dropping low-signal noise, highlighting distinct meaningful efforts, and avoiding changelog-style wording, unsupported claims, needless commit-range questions, or commit-selection UI for ordinary branch-level squash requests. | | [skill-creator-agnostic](skills/skill-creator-agnostic/SKILL.md) | Runner-agnostic overlay for Anthropic `skill-creator`. Adds repo and environment guardrails for skill authoring and benchmarking: temp-workspace isolation, `iteration-N/eval-name/{config}/run-N/` benchmark layout, valid `grading.json` summaries, generated `benchmark.json`, honest `MEASURED` vs `SIMULATED` labeling, and sync/README discipline for repo-managed skills. | | [markdown-illustrator](skills/markdown-illustrator/SKILL.md) | Reads a markdown file and answers directly in chat with one document-wide Visual Brief plus one compiled prompt. Infers a compact visual strategy by default, keeps follow-up questions near zero, and only branches when the user explicitly asks for added specificity. | | [dotnet-new-lib-slnx](skills/dotnet-new-lib-slnx/SKILL.md) | Scaffold a new .NET NuGet library solution following codebeltnet engineering conventions. Dynamic defaults for TFM/repository metadata, latest-stable NuGet package resolution, tuning projects plus a tooling-based benchmark runner, TFM-aware test environments, strong-name signing, NuGet packaging, DocFX documentation, CI/CD pipeline, and code quality tooling. | @@ -161,10 +161,18 @@ Commit messages are the most-read documentation in any codebase — yet they're **git-visual-commits** handles the entire commit workflow— staging, diffing, crafting the message, choosing the right emoji — so every commit is consistent and meaningful without breaking your flow. Whether the agent authors the commit (`git bot commit`), you do (`git commit`), or you worked on it together (`git our commit`), the quality is the same. - **Gitmoji-first** — visual commit categories that are scannable at a glance -- **Conventional prefixes** — `init`, `content`, `style`, `fix`, `refactor`, and `docs` as fallback when gitmoji isn't available +- **Emoji-first by default** — the normal subject shape is ` `, not ` : ...` +- **Conventional-prefix combo is opt-in** — `init`, `content`, `style`, `fix`, `refactor`, and `docs` are available only when you explicitly ask to combine emoji with conventional-commit prefixes - **Three identity modes** — bot, human, or collaborative — the agent does the work either way, you choose who gets credit - **Identity lock stays honest** — `git bot commit` means bot attribution, not just "AI did the work", and the flow now verifies the resulting author after commit +- **Direct git execution for bot identity** — identity-sensitive commit paths should use direct shell/terminal git commands, not wrappers that may bypass aliases +- **Clarifies before correcting** — vague feedback like "4 is wrong" triggers a short question, not a guessed revert or regrouping +- **Evidence-backed explanations** — emoji and grouping justifications stay tied to references actually inspected in the session +- **Reference-validated emoji choices** — the workflow reads the bundled `commit-language.md` skill resource before proposing commit subjects and does not treat a missing repo-root `references/` folder as the same thing as a missing skill reference +- **Community health uses `💬`** — changelogs and repo-health / release-status communication are treated as human-facing messaging, not generic `📝` or `📚` docs by default +- **Skill refactors map to refactor intent** — reorganizing an existing skill's wording or eval contract should land on `♻️`, not a guessed new-feature or config emoji - **Auto-approval** — say "yolo" or "auto" to skip the review gate when you trust the agent's judgment +- **No `yolo`, no commit** — without `yolo` / `auto` or an already-enabled auto mode, the workflow must stop at the plan and wait for approval before it commits anything - **Yolo skips confirmation, not discipline** — auto-approval still requires semantic grouping, mixed-scope checks, and a visible commit plan summary before committing - **Full worktree by default** — plain `git bot commit yolo` means "commit everything currently in git status and group it correctly", not "guess a narrower slice" - **Commit body by default** — every commit explains *why*, not just *what* — opt out with "tmi" or "no-body" @@ -173,6 +181,11 @@ Commit messages are the most-read documentation in any codebase — yet they're - **Repo capability additions stay explicit** — adding a brand-new skill is grouped separately from refactoring an existing skill to support it - **Shared wording rules stay in lockstep** — the duplicated `commit-language.md` reference is kept byte-for-byte identical across both git-visual skills and checked locally plus in CI - **Semantic intent splitting** — groups commits by rationale, not just file type — config and test logic are always separate +- **Same-round edits are not one commit by default** — temporal proximity never outranks semantic intent when grouping changes +- **Release-adjacent work still splits cleanly** — dependency baselines, package metadata, community health docs, doc publishing fixes, and CI automation can belong in separate commits even when they land together +- **Package release notes are `📦` work** — `.nuget/*/PackageReleaseNotes.txt` belongs with package/publish metadata, not with `💬` community-health communication +- **Tool-path failures fail fast** — a wrong-author first attempt means switch execution path immediately instead of retrying the same broken wrapper +- **Recovery stays conservative** — prefer inspecting git state and stashing before broad restore/reset commands when commit repair goes sideways - **Umbrella commits are rejected** — mixed diffs spanning skill instructions, templates, validators, and repo docs must be split into separate commits instead of bundled into one blob - **Stack-agnostic** — works with any language, framework, or project type - **Squash-and-merge friendly** — structured commits make PR squash summaries read like a changelog @@ -181,12 +194,17 @@ Commit messages are the most-read documentation in any codebase — yet they're Sometimes the history is already written and the only thing you need is the final grouped summary. A long branch with fixups, rename follow-ups, review nits, and repeated attempts often contains a few real change themes buried inside a messy chronological story. That is where **git-visual-squash-summary** fits: it reads the real history and diff, then compresses them into a small set of truthful grouped lines. -- **Same visual language** — reuses the same prefix and emoji rules as `git-visual-commits` +- **Same visual language** — reuses the same emoji-first wording rules as `git-visual-commits` - **Grouped-lines only** — returns compact grouped lines only, not a title or body - **Non-mutating by design** — drafts the wording only and does not touch git state +- **Whole-branch by default** — for squash-and-merge requests, uses the full current feature branch from merge-base to `HEAD` instead of asking which branch commits to include +- **Bare invocation means summarize now** — calling `git-visual-squash-summary` directly should resolve the current branch scope automatically and return the grouped lines, not a "what do you want me to summarize?" question +- **No commit-picker UX** — ordinary branch-level squash requests do not become commit-selection questions or widgets; the skill resolves the branch scope and writes the summary - **Distinct efforts stay distinct** — preserves meaningful change groups instead of forcing one umbrella line +- **Dependency updates stay explicit** — package/version baseline changes keep their own dependency-focused line instead of getting absorbed into generic build-system or refactor wording - **Intent over chronology** — collapses noisy commit stacks into the retained grouped effort - **Low-signal noise gets dropped** — typo-only and trivial fixup churn do not deserve their own lines +- **Late release-prep commits stay in scope** — changelog, version-bump, and release-finalization follow-ups are treated as part of the branch by default and then merged or dropped during semantic collapsing - **Identifier-safe wording** — preserves technical names, paths, flags, and types where possible - **Readable in GitHub and terminals** — optimized for compact PR and squash-summary views - **Strict 72-char lines** — every summary line stays compact and scannable @@ -200,6 +218,7 @@ Writing `CHANGELOG.md` well is harder than it looks. Raw commit subjects are too - **Keep a Changelog first** — writes `Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, and `Security` sections in the expected style - **Full-commit context** — reads complete commit messages and the net diff before writing - **Version-aware by branch** — uses a branch prefix like `v0.3.0/...` as the release heading hint when present +- **Mandatory pending-worktree gate** — when a concrete release has uncommitted changes, the skill must ask a short `Yes / No / Custom` confirmation question before folding them into the changelog draft, with a `FORMS.md` definition that compatible hosts can render as native choices - **SemVer-aware highlight** — always writes a short release TL;DR that explicitly says `major`, `minor`, or `patch` - **Creates the file when needed** — seeds a compliant `CHANGELOG.md` if the repo does not have one yet - **Natural prose** — preserves human-readable line breaks without any fixed-width wrapping target @@ -246,7 +265,8 @@ Anthropic's `skill-creator` is an excellent base workflow, but the day-to-day fr - **Benchmark-contract aware** — enforces `iteration-N/eval-name/{config}/run-N/`, valid `grading.json.summary`, and generated `benchmark.json` - **Tool-path explicit** — points authors to the installed Anthropic `skill-creator` copy that provides `scripts/aggregate_benchmark.py` and `eval-viewer/generate_review.py` - **Honest benchmark modes** — keeps `MEASURED` and `SIMULATED` runs clearly separated so pipeline validation never masquerades as model quality -- **PowerShell-safe** — calls out UTF-8 no BOM, stable counting, provider-path normalization, and other Windows-specific pitfalls +- **PowerShell-safe** — calls out UTF-8 no BOM, `PYTHONUTF8`, stable counting, provider-path normalization, prompt-passing pitfalls, and other Windows-specific benchmark traps +- **Codex-friendly benchmarking** — treats Codex CLI as a valid real runner when present, preserves `MEASURED` parity honestly, uses raw event output as fallback evidence when convenience files are missing, and prefers parallel paired runs when the runner supports sub-agents - **Repo-managed discipline** — keeps per-skill evals, local-install sync, and README updates in scope for first-party skills ### Why markdown-illustrator? @@ -265,6 +285,7 @@ Markdown-heavy documents often need one image that sells the whole idea fast: a - **Anti-repetition by default** — avoids repeated labels, bullets, steps, callouts, mirrored panels, and echoed document fragments so the image reads like one authoritative artifact rather than many near-duplicates - **No selection detours** — skips file creation, model-family, style, theme, and scope menus so the workflow stays fast and focused - **User steerable when needed** — the skill stays minimal, but users can still explicitly steer toward directions like `whiteboard`, `blackboard`, `isometric`, or `blueprint` +- **Board styles use color intentionally** — `whiteboard` and `blackboard` keep their authentic marker/chalk base, but the skill now biases toward selective colored accents for arrows, icons, checks, and highlights instead of leaving every emphasis mark monochrome #### Inferred Defaults For markdown-illustrator @@ -295,13 +316,13 @@ These are reference directions for users, not built-in branches in the skill. If - Pros: approachable, collaborative, strong for brainstorming, product planning, workshops, and messy human energy - Cons: can feel too casual or cluttered for polished keynote or editorial uses -- Guidance: ask for this when the document is about ideation, strategy sessions, or product thinking +- Guidance: ask for this when the document is about ideation, strategy sessions, or product thinking; expect a mostly marker-based board with selective colored accents for emphasis marks instead of pure black-only linework `blackboard` - Pros: dramatic, intellectual, layered, great for systems thinking and technical storytelling - Cons: can become visually noisy if the source material is already dense -- Guidance: ask for this when the document is about architecture, strategy, layered concepts, or technical explanation +- Guidance: ask for this when the document is about architecture, strategy, layered concepts, or technical explanation; expect a chalkboard base with restrained colored chalk accents for arrows, highlights, and key icons instead of all-white chalk marks `isometric` diff --git a/scripts/validate-skill-templates.ps1 b/scripts/validate-skill-templates.ps1 index d85f861..1add7f1 100644 --- a/scripts/validate-skill-templates.ps1 +++ b/scripts/validate-skill-templates.ps1 @@ -668,7 +668,19 @@ Add-ValidationResult -Results $results -Name 'Git visual commits skill enforces Assert-Contains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle '### Identity Lock' Assert-Contains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle 'Never silently downgrade a requested `git bot commit` to `git commit`.' Assert-Contains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle 'If the required `git bot` alias is unavailable, halt and report that exact blocker instead of falling back to human identity.' + Assert-Contains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle '### Direct Git Execution Rule' + Assert-Contains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle 'prefer direct shell or terminal execution of git commands over wrapper tools' + Assert-Contains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle '### Fail-Fast Tool Validation' + Assert-Contains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle 'Pivot immediately to a direct shell or terminal git path instead of retrying with the same broken wrapper.' + Assert-Contains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle '### Recovery Safety Rule' + Assert-Contains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle 'Prefer non-destructive recovery first: targeted unstaging, precise re-staging, or `git stash`' Assert-Contains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle '`yolo` / `auto` skips user confirmation only.' + Assert-Contains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle 'If the user did **not** say `yolo` or `auto`, and session-level auto mode is not already enabled, do **not** run any commit command yet.' + Assert-Contains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle '### Commit Language Lock' + Assert-Contains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle 'Resolve that path from this skill''s own bundled `references/` directory or installed skill folder first.' + Assert-Contains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle 'If the current repository has no `references/commit-language.md` file but the bundled skill reference is available, that is **not** a blocker.' + Assert-Contains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle 'Default to ` `.' + Assert-Contains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle 'Do not add a prefix after the emoji unless the user explicitly asked for a combo with conventional commits or conventional prefixes.' Assert-Contains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle 'After every commit, run:' Assert-Contains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle 'git log -1 --format="%an <%ae>"' Assert-Contains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle 'git log -1 --format=%B' @@ -677,6 +689,9 @@ Add-ValidationResult -Results $results -Name 'Git visual commits skill enforces Assert-Contains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle '### Umbrella Commit Rejection' Assert-Contains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle 'skill instructions (`SKILL.md`, `FORMS.md`, `references/`, `evals/`)' Assert-Contains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle 'Read `references/commit-language.md` before choosing a prefix or emoji.' + Assert-Contains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle 'Treat `references/commit-language.md` as a bundled skill resource path, not as a repository-relative path.' + Assert-Contains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle 'That reference now defines prefixes as opt-in.' + Assert-Contains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle 'Treat community health, changelog, and release-status communication as' Assert-NotContains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle '### Allowed Prefixes' Assert-NotContains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle '### Emoji Selection' Assert-Contains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle 'Even in auto-approval mode, surface the commit buckets explicitly before committing.' @@ -687,6 +702,15 @@ Add-ValidationResult -Results $results -Name 'Git visual commits skill enforces Assert-Contains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle 'introducing a new repo-managed skill, workflow, or top-level capability' Assert-Contains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle '**Existing skill refactors**' Assert-Contains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle 'restructuring or extracting shared rules from an already existing skill' + Assert-Contains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle '**Dependency/version baselines**' + Assert-Contains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle '**Package/publish metadata**' + Assert-Contains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle '**Documentation publishing**' + Assert-Contains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle '**Community health/release communication**' + Assert-Contains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle 'Temporal proximity is not a grouping signal.' + Assert-Contains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle '#### Release-adjacent splitting rule' + Assert-Contains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle 'Concrete example: if one diff updates `Directory.Build.targets`, `Directory.Packages.props`, or `testenvironments.json`,' + Assert-Contains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle 'Keep `.nuget/*/PackageReleaseNotes.txt` with the' + Assert-Contains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle 'The rule is the abstraction: split by purpose and audience, not by the fact that the changes landed together.' Assert-Contains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle 'do not collapse "new skill introduced" and "existing skill refactored" into one commit' Assert-Contains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle '**New repo-managed skill**' Assert-Contains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle 'a newly introduced `skills//` folder and its local `evals/` or `references/`' @@ -695,6 +719,8 @@ Add-ValidationResult -Results $results -Name 'Git visual commits skill enforces Assert-Contains -Name 'git-visual-commits/references/commit-language.md' -Content $commitLanguage -Needle '### Emoji Selection' Assert-Contains -Name 'git-visual-commits/references/commit-language.md' -Content $commitLanguage -Needle 'Gitmoji First, Fallback Second' Assert-Contains -Name 'git-visual-commits/references/commit-language.md' -Content $commitLanguage -Needle '#### Fallback: Extended Emoji Reference' + Assert-Contains -Name 'git-visual-commits/references/commit-language.md' -Content $commitLanguage -Needle 'Community health, changelog, release-status communication' + Assert-Contains -Name 'git-visual-commits/references/commit-language.md' -Content $commitLanguage -Needle 'package release-note metadata' Assert-Contains -Name 'git-visual-commits/evals/evals.json' -Content $evals -Needle 'Does not let yolo collapse multiple semantic intents into one umbrella commit' Assert-Contains -Name 'git-visual-commits/evals/evals.json' -Content $evals -Needle 'Verifies the commit author after commit and confirms it matches bot identity' @@ -703,6 +729,19 @@ Add-ValidationResult -Results $results -Name 'Git visual commits skill enforces Assert-Contains -Name 'git-visual-commits/evals/evals.json' -Content $evals -Needle 'stops with a clear alias-missing error instead of silently falling back to human identity' Assert-Contains -Name 'git-visual-commits/evals/evals.json' -Content $evals -Needle 'Treats a newly introduced skill folder as a separate repo capability intent' Assert-Contains -Name 'git-visual-commits/evals/evals.json' -Content $evals -Needle 'Separates new skill introduction from existing skill refactor work' + Assert-Contains -Name 'git-visual-commits/evals/evals.json' -Content $evals -Needle 'Does not use same-round timing as a reason to merge everything into one commit' + Assert-Contains -Name 'git-visual-commits/evals/evals.json' -Content $evals -Needle 'community health or changelog commit based on commit-language.md instead of a generic docs emoji' + Assert-Contains -Name 'git-visual-commits/evals/evals.json' -Content $evals -Needle 'Presents the grouping as high-level semantic intents rather than a brittle filename-only rule' + Assert-Contains -Name 'git-visual-commits/evals/evals.json' -Content $evals -Needle 'Treats a wrong-author first attempt as a tool-path failure instead of retrying multiple times with the same wrapper' + Assert-Contains -Name 'git-visual-commits/evals/evals.json' -Content $evals -Needle 'Prefers non-destructive recovery such as inspecting git state or using stash before broad restore or reset commands' + Assert-Contains -Name 'git-visual-commits/evals/evals.json' -Content $evals -Needle 'Does not add conventional prefixes after the emoji when the user did not explicitly ask for that combo' + Assert-Contains -Name 'git-visual-commits/evals/evals.json' -Content $evals -Needle 'Classifies an existing skill wording or contract reorganization as refactor intent instead of guessing new-feature or configuration intent' + Assert-Contains -Name 'git-visual-commits/evals/evals.json' -Content $evals -Needle 'Treats emoji plus conventional-prefix formatting as opt-in rather than default' + Assert-Contains -Name 'git-visual-commits/evals/evals.json' -Content $evals -Needle 'Treats the absence of yolo or auto as a requirement to stop for approval before any commit command runs' + Assert-Contains -Name 'git-visual-commits/evals/evals.json' -Content $evals -Needle 'Separates .nuget package release notes into the package or publish metadata commit' + Assert-Contains -Name 'git-visual-commits/evals/evals.json' -Content $evals -Needle 'package release notes or package metadata work instead of the community-health emoji' + Assert-Contains -Name 'git-visual-commits/evals/evals.json' -Content $evals -Needle 'Treats references/commit-language.md as a bundled skill resource rather than a repo-root path by default' + Assert-Contains -Name 'git-visual-commits/evals/evals.json' -Content $evals -Needle 'Does not report a blocker solely because the current repository lacks a top-level references directory' } Add-ValidationResult -Results $results -Name 'Git visual squash summary skill stays self-contained and shares commit language rules' -Action { @@ -718,12 +757,16 @@ Add-ValidationResult -Results $results -Name 'Git visual squash summary skill st Assert-Contains -Name 'git-visual-squash-summary/SKILL.md' -Content $skill -Needle 'This skill turns a stack of commits into a curated grouped summary' Assert-Contains -Name 'git-visual-squash-summary/SKILL.md' -Content $skill -Needle 'This skill is non-mutating:' Assert-Contains -Name 'git-visual-squash-summary/SKILL.md' -Content $skill -Needle 'Retain only distinct high-signal change groups.' - Assert-Contains -Name 'git-visual-squash-summary/SKILL.md' -Content $skill -Needle 'Read `references/commit-language.md` before choosing any emoji or prefix.' + Assert-Contains -Name 'git-visual-squash-summary/SKILL.md' -Content $skill -Needle 'Read `references/commit-language.md` before choosing any emoji or optional prefix.' + Assert-Contains -Name 'git-visual-squash-summary/SKILL.md' -Content $skill -Needle 'Default to emoji plus description only.' Assert-Contains -Name 'git-visual-squash-summary/SKILL.md' -Content $skill -Needle 'Favor readable GitHub and terminal output over cleverness.' Assert-Contains -Name 'git-visual-squash-summary/SKILL.md' -Content $skill -Needle 'Do not treat the result as a changelog entry or a dump of commit subjects.' Assert-Contains -Name 'git-visual-squash-summary/SKILL.md' -Content $skill -Needle 'Return grouped lines only, never a title or body.' Assert-Contains -Name 'git-visual-squash-summary/SKILL.md' -Content $skill -Needle 'Keep every output line at or below 72 characters.' Assert-Contains -Name 'git-visual-squash-summary/SKILL.md' -Content $skill -Needle 'Do not invent unsupported changes.' + Assert-Contains -Name 'git-visual-squash-summary/SKILL.md' -Content $skill -Needle 'A bare invocation such as `git-visual-squash-summary` or `/git-visual-squash-summary` is itself a complete request' + Assert-Contains -Name 'git-visual-squash-summary/SKILL.md' -Content $skill -Needle 'Do not open with "What would you like me to summarize?"' + Assert-Contains -Name 'git-visual-squash-summary/SKILL.md' -Content $skill -Needle 'If a retained line is mainly changelog, community-health, or release-status communication, prefer' Assert-Contains -Name 'git-visual-squash-summary/SKILL.md' -Content $skill -Needle 'Do not append weak glue like "with", "plus", or "and" just to force' Assert-Contains -Name 'git-visual-squash-summary/SKILL.md' -Content $skill -Needle 'Fits naturally beneath a PR title or in compact GitHub and terminal views.' Assert-Contains -Name 'git-visual-squash-summary/SKILL.md' -Content $skill -Needle 'Changelog-like wording or release-note phrasing.' @@ -744,10 +787,14 @@ Add-ValidationResult -Results $results -Name 'Git visual squash summary skill st Assert-Contains -Name 'git-visual-squash-summary/evals/evals.json' -Content $evals -Needle 'Does not treat the result as a changelog entry or commit-subject dump' Assert-Contains -Name 'git-visual-squash-summary/evals/evals.json' -Content $evals -Needle 'Highlights distinct meaningful efforts instead of forcing one dominant umbrella theme' Assert-Contains -Name 'git-visual-squash-summary/evals/evals.json' -Content $evals -Needle 'Does not invent unsupported changes' + Assert-Contains -Name 'git-visual-squash-summary/evals/evals.json' -Content $evals -Needle 'Defaults to emoji plus description lines without adding conventional prefixes' + Assert-Contains -Name 'git-visual-squash-summary/evals/evals.json' -Content $evals -Needle 'If a retained line is mainly changelog or release-status communication, prefers' + Assert-Contains -Name 'git-visual-squash-summary/evals/evals.json' -Content $evals -Needle 'Treats a bare skill invocation as a complete request to summarize the current branch' } Add-ValidationResult -Results $results -Name 'Git keep a changelog skill updates CHANGELOG.md from git history' -Action { $skill = Get-FileText -RepoRoot $repoRoot -RelativePath 'skills/git-keep-a-changelog/SKILL.md' -GitRef $Ref + $forms = Get-FileText -RepoRoot $repoRoot -RelativePath 'skills/git-keep-a-changelog/FORMS.md' -GitRef $Ref $evals = Get-FileText -RepoRoot $repoRoot -RelativePath 'skills/git-keep-a-changelog/evals/evals.json' -GitRef $Ref Assert-Contains -Name 'git-keep-a-changelog/SKILL.md' -Content $skill -Needle 'Create or update `CHANGELOG.md` directly, then stop for user review.' @@ -757,14 +804,28 @@ Add-ValidationResult -Results $results -Name 'Git keep a changelog skill updates Assert-Contains -Name 'git-keep-a-changelog/SKILL.md' -Content $skill -Needle 'Otherwise, target `## [Unreleased]`.' Assert-Contains -Name 'git-keep-a-changelog/SKILL.md' -Content $skill -Needle 'Always write a release highlight immediately below the target heading.' Assert-Contains -Name 'git-keep-a-changelog/SKILL.md' -Content $skill -Needle 'The release highlight must explicitly classify the release as `major`,' + Assert-Contains -Name 'git-keep-a-changelog/SKILL.md' -Content $skill -Needle '## Mandatory Checkpoints' + Assert-Contains -Name 'git-keep-a-changelog/SKILL.md' -Content $skill -Needle 'These checkpoints cannot be skipped or bypassed' + Assert-Contains -Name 'git-keep-a-changelog/SKILL.md' -Content $skill -Needle '## User Intent vs. Mandatory Gates' + Assert-Contains -Name 'git-keep-a-changelog/SKILL.md' -Content $skill -Needle 'The Step 3 confirmation gate exists to prevent silent inclusion' Assert-Contains -Name 'git-keep-a-changelog/SKILL.md' -Content $skill -Needle 'Use the standard Keep a Changelog section order:' Assert-Contains -Name 'git-keep-a-changelog/SKILL.md' -Content $skill -Needle 'Preserve natural line breaks and readable prose. Do not apply any fixed' Assert-Contains -Name 'git-keep-a-changelog/SKILL.md' -Content $skill -Needle 'End each bullet with `,` and end the last bullet in each section with' + Assert-Contains -Name 'git-keep-a-changelog/SKILL.md' -Content $skill -Needle '### Step 3: Confirm Pending Worktree Changes (MANDATORY GATE)' + Assert-Contains -Name 'git-keep-a-changelog/SKILL.md' -Content $skill -Needle 'This is a required checkpoint. Do not proceed to Step 4 until this step is complete.' + Assert-Contains -Name 'git-keep-a-changelog/SKILL.md' -Content $skill -Needle 'you must ask a direct confirmation question before drafting the changelog entry.' + Assert-Contains -Name 'git-keep-a-changelog/SKILL.md' -Content $skill -Needle 'Do not skip this question.' + Assert-Contains -Name 'git-keep-a-changelog/SKILL.md' -Content $skill -Needle 'Wait for the user''s explicit response before proceeding to Step 4.' Assert-Contains -Name 'git-keep-a-changelog/SKILL.md' -Content $skill -Needle 'Do not dump commit subjects verbatim into the changelog.' Assert-Contains -Name 'git-keep-a-changelog/SKILL.md' -Content $skill -Needle 'If `CHANGELOG.md` is missing, create it with the standard title,' - Assert-Contains -Name 'git-keep-a-changelog/SKILL.md' -Content $skill -Needle 'Update compare links at the bottom when adding a concrete version:' + Assert-Contains -Name 'git-keep-a-changelog/SKILL.md' -Content $skill -Needle 'Always maintain the Keep a Changelog compare-link footer at the bottom of the file.' + Assert-Contains -Name 'git-keep-a-changelog/SKILL.md' -Content $skill -Needle 'On every edit, verify that the compare-link footer exists at the bottom of the file.' Assert-Contains -Name 'git-keep-a-changelog/SKILL.md' -Content $skill -Needle 'Do not commit, tag, push, or create a release unless the user asks.' + Assert-Contains -Name 'git-keep-a-changelog/FORMS.md' -Content $forms -Needle 'This is the mandatory Step 3 confirmation gate for concrete releases.' + Assert-Contains -Name 'git-keep-a-changelog/FORMS.md' -Content $forms -Needle 'I found pending changes not yet committed for release `{release_label}`: `{staged_count}` staged, `{unstaged_count}` unstaged, `{untracked_count}` untracked. Include them in the changelog draft? Yes / No / Custom' + Assert-Contains -Name 'git-keep-a-changelog/FORMS.md' -Content $forms -Needle 'Do not skip this gate when the target is a concrete release' + Assert-Contains -Name 'git-keep-a-changelog/evals/evals.json' -Content $evals -Needle 'Updates CHANGELOG.md directly instead of only drafting notes in chat' Assert-Contains -Name 'git-keep-a-changelog/evals/evals.json' -Content $evals -Needle 'Reads full commit subjects and bodies before writing the release entry' Assert-Contains -Name 'git-keep-a-changelog/evals/evals.json' -Content $evals -Needle 'Treats a leading branch version such as v0.3.0/ as a release hint' @@ -772,6 +833,9 @@ Add-ValidationResult -Results $results -Name 'Git keep a changelog skill updates Assert-Contains -Name 'git-keep-a-changelog/evals/evals.json' -Content $evals -Needle 'Preserves natural prose wrapping instead of forcing any fixed column width' Assert-Contains -Name 'git-keep-a-changelog/evals/evals.json' -Content $evals -Needle 'Ends bullets with commas and ends the final bullet in each section with a period' Assert-Contains -Name 'git-keep-a-changelog/evals/evals.json' -Content $evals -Needle 'Creates CHANGELOG.md when it does not already exist' + Assert-Contains -Name 'git-keep-a-changelog/evals/evals.json' -Content $evals -Needle 'Treats the pending-worktree question as a mandatory gate before Step 4 for a concrete release' + Assert-Contains -Name 'git-keep-a-changelog/evals/evals.json' -Content $evals -Needle 'Does not let user intent bypass the mandatory pending-worktree confirmation gate for a concrete release' + Assert-Contains -Name 'git-keep-a-changelog/evals/evals.json' -Content $evals -Needle 'Inserts the compare-link footer at the bottom when it is missing from an existing changelog' } Add-ValidationResult -Results $results -Name 'Rendered app worker template leaves no unexpected placeholders' -Action { diff --git a/skills/dotnet-strong-name-signing/SKILL.md b/skills/dotnet-strong-name-signing/SKILL.md index 03c6625..651899c 100644 --- a/skills/dotnet-strong-name-signing/SKILL.md +++ b/skills/dotnet-strong-name-signing/SKILL.md @@ -1,11 +1,13 @@ --- name: dotnet-strong-name-signing -description: > - Generate a strong name key (.snk) file for signing .NET assemblies using pure .NET cryptography — no Visual Studio Developer PowerShell or sn.exe required. Works in any terminal. Use this skill when the user wants to create a strong name key, generate an .snk file, sign .NET assemblies, or mentions "strong-name", "snk", "AssemblyOriginatorKeyFile", "SignAssembly", or asks how to sign a .NET library. Also use when scaffolding .NET libraries or NuGet packages that need assembly signing. ALWAYS use this skill when asked to generate or create a strong name key file. +description: > + Generate a strong name key (.snk) file for signing .NET assemblies using pure .NET cryptography — no Visual Studio Developer PowerShell or sn.exe required. Works in any terminal. Use this skill when the user wants to create a strong name key, generate an .snk file, sign .NET assemblies, or mentions "strong-name", "snk", "AssemblyOriginatorKeyFile", "SignAssembly", or asks how to sign a .NET library. Also use when scaffolding .NET libraries or NuGet packages that need assembly signing. ALWAYS use this skill when asked to generate or create a strong name key file. --- # Strong Name Signing for .NET +![Strong Name Signing](assets/hero.jpg) + Generate a strong name key pair (`.snk` file) for signing .NET assemblies. Uses the .NET runtime's built-in `RSACryptoServiceProvider` instead of `sn.exe`, so it works in **any PowerShell or terminal** — no Visual Studio Developer Command Prompt needed. ## Why this matters @@ -31,9 +33,9 @@ $keyBlob = $rsa.ExportCspBlob($true) $rsa.Dispose() ``` -Where: -- `{KEY_SIZE}` — RSA key size from parameters (default: 1024) -- `{OUTPUT_PATH}` — full path combining `{OUTPUT_DIR}` and `{KEY_NAME}.snk` +Where: +- `{KEY_SIZE}` — RSA key size from parameters (default: 1024) +- `{OUTPUT_PATH}` — full path combining `{OUTPUT_DIR}` and `{KEY_NAME}.snk` The `ExportCspBlob($true)` method exports the full key pair (public + private) in the exact CSP blob format that `sn.exe -k` produces. The `$true` parameter includes the private key — essential for signing during builds. diff --git a/skills/dotnet-strong-name-signing/assets/hero.jpg b/skills/dotnet-strong-name-signing/assets/hero.jpg new file mode 100644 index 0000000..c417aee Binary files /dev/null and b/skills/dotnet-strong-name-signing/assets/hero.jpg differ diff --git a/skills/git-keep-a-changelog/FORMS.md b/skills/git-keep-a-changelog/FORMS.md new file mode 100644 index 0000000..58528e2 --- /dev/null +++ b/skills/git-keep-a-changelog/FORMS.md @@ -0,0 +1,61 @@ +# Parameter Form + +Use this form only when pending worktree changes are detected and the skill must ask whether they belong in the changelog draft. This is the mandatory Step 3 confirmation gate for concrete releases. Present each field **one at a time** using the host's native structured input controls when available. If native controls are unavailable, use the deterministic plain-text fallback below. Do not use this form when there are no pending changes to confirm. + +## Fields + +### include_pending_changes +- **type:** single-choice +- **prompt:** "I found pending changes not yet committed for release `{release_label}`: `{staged_count}` staged, `{unstaged_count}` unstaged, `{untracked_count}` untracked. Include them in the changelog draft? Yes / No / Custom" +- **choices:** + - Yes + - No + - Custom +- **default:** No +- **required:** true +- **description:** `Yes` includes the pending staged, unstaged, and untracked changes in addition to the committed range. `No` uses committed history only. `Custom` lets the user narrow the pending scope. + +### custom_pending_scope +- **type:** text +- **prompt:** "Which pending changes should I include?" +- **choices:** none +- **default:** none +- **placeholder:** "e.g. staged only, exclude untracked" +- **required:** true +- **description:** Ask this field only when `include_pending_changes` is `Custom`. + +## Presentation Rules + +1. Compute the dynamic prompt values from the actual repo state before showing the form: + - `{release_label}` = the visible changelog target such as `1.2.3` or `Unreleased` + - `{staged_count}` = count of staged changes + - `{unstaged_count}` = count of unstaged tracked changes + - `{untracked_count}` = count of untracked files +2. Ask one field at a time — wait for the answer before presenting the next field. +3. Prefer the host's native structured input controls for the `include_pending_changes` field when they are available. +4. If native structured input controls are unavailable, use this exact plain-text fallback for the first field: + ```text + Field: include_pending_changes + I found pending changes not yet committed for release {release_label}: {staged_count} staged, {unstaged_count} unstaged, {untracked_count} untracked. Include them in the changelog draft? Yes / No / Custom + 1. Yes + 2. No + 3. Custom + ``` +5. In the plain-text fallback, allow the user to answer with either the number or the exact option text, then restate the normalized value in one short line before moving on. +6. Ask `custom_pending_scope` only when the chosen value is `Custom`. +7. Keep the meaning stable across both input modes: + - `Yes` = include all pending staged, unstaged, and untracked changes in addition to the committed range + - `No` = use committed history only + - `Custom` = collect a narrower pending-change scope such as `staged only` +8. After all fields are collected, present this short summary and ask for confirmation before proceeding: + ```text + Pending change handling: + Release: {release_label} + Staged: {staged_count} + Unstaged: {unstaged_count} + Untracked: {untracked_count} + Decision: {resolved_scope} + + Proceed with this changelog scope? + ``` +9. Do not skip this gate when the target is a concrete release, even if the user's request says `include everything`, `all changes`, `commit manually`, or `don't ask`. diff --git a/skills/git-keep-a-changelog/SKILL.md b/skills/git-keep-a-changelog/SKILL.md index 08cad50..4cc3318 100644 --- a/skills/git-keep-a-changelog/SKILL.md +++ b/skills/git-keep-a-changelog/SKILL.md @@ -1,13 +1,17 @@ --- name: git-keep-a-changelog description: > - Create or update CHANGELOG.md from git history using Keep a Changelog 1.1.0 style. Use when the user asks to create/update changelog, draft release notes, or mentions SemVer-aware summaries. Trigger phrases: "finalize", "ready to release", "rtr", "release" (especially with version branches like v0.3.1/...). Reads full commit bodies and diffs, creates compliant structure with required SemVer highlights, infers versions from branches, edits directly for review, preserves prose wrapping, avoids commit-log dumps. + Create or update CHANGELOG.md from git history using Keep a Changelog 1.1.0 style. Use when the user asks to create/update changelog, draft release notes, or mentions SemVer-aware summaries. Trigger phrases: "finalize", "ready to release", "rtr", "release" (especially with version branches like v0.3.1/...). Reads full commit bodies and diffs, creates compliant structure with required SemVer highlights, infers versions from branches, must ask a mandatory Yes / No / Custom confirmation question before including pending staged, unstaged, or untracked worktree changes in a concrete release draft, edits directly for review, preserves prose wrapping, avoids commit-log dumps. --- # Git Keep A Changelog +![Git Keep A Changelog](assets/hero.jpg) + This skill creates or updates `CHANGELOG.md` directly using the Keep a Changelog 1.1.0 structure. It is git-aware, changelog-focused, and optimized for a human-readable release summary rather than generated release-note noise. +Read `FORMS.md` when pending worktree changes require user confirmation and the host supports native structured input controls. If native structured input is unavailable, use the deterministic plain-text fallback defined there. + ## Non-Negotiable Rules - Create or update `CHANGELOG.md` directly, then stop for user review. @@ -20,11 +24,21 @@ This skill creates or updates `CHANGELOG.md` directly using the Keep a Changelog - The release highlight must explicitly classify the release as `major`, `minor`, or `patch`. - Use the standard Keep a Changelog section order: `Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, `Security`. - Omit empty sections instead of emitting placeholders. +- Always maintain the Keep a Changelog compare-link footer at the bottom of the file. - Preserve natural line breaks and readable prose. Do not apply any fixed column limit or artificial hard wrapping to changelog paragraphs or bullets. - End each bullet with `,` and end the last bullet in each section with `.`. +- If pending worktree changes exist for a concrete release draft, do not silently include or exclude them. Ask the user first with a short `Yes / No / Custom` prompt. - Do not dump commit subjects verbatim into the changelog. - Do not invent unsupported changes, risks, or migration guidance. +## Mandatory Checkpoints + +These checkpoints cannot be skipped or bypassed, even when the user's opening request sounds like a shortcut. + +1. Step 3 confirmation gate: if pending worktree changes exist for a concrete release such as `## [1.2.3]`, present the confirmation question before drafting or writing the changelog entry. +2. Release highlight contract: every concrete release entry must include a release highlight paragraph that explicitly classifies the release as `major`, `minor`, or `patch`. +3. Bullet punctuation: all bullets must end with `,` except the final bullet in each populated section, which must end with `.` Do not finish the edit until this is consistent. + ## Release Highlight Contract Every updated changelog entry must begin with a short human-written highlight paragraph directly below the heading. @@ -57,6 +71,24 @@ When the history clearly carries migration risk or upgrade caveats, add an advis Only add callouts when the commits or diff justify them. +## User Intent vs. Mandatory Gates + +### User intent can refine scope after the gate + +Explicit instructions such as `staged only`, `include unstaged changes`, or `exclude untracked` can refine the changelog scope after the Step 3 confirmation gate has been presented and answered. + +### User intent cannot bypass the gate + +- Do not skip Step 3 just because the user says `include everything`, `all changes`, `commit manually`, or `don't ask`. +- Do not omit the release highlight paragraph for a concrete release. +- Do not omit the explicit `major`, `minor`, or `patch` classification. + +The Step 3 confirmation gate exists to prevent silent inclusion of worktree changes in a permanent release entry. It is a required safety checkpoint, not optional friction. + +### Why this matters + +Silent inclusion of pending changes in a changelog is a production risk. The gate ensures the release scope is intentional, visible, and explicitly confirmed before the draft becomes part of the project's recorded release history. + ## Workflow ### Step 1: Resolve the source range @@ -94,12 +126,48 @@ Otherwise: - If no version hint exists, target `## [Unreleased]`. - If the target heading already exists, update it in place instead of duplicating it. -### Step 3: Read the full history and net effect +### Step 3: Confirm Pending Worktree Changes (MANDATORY GATE) + +This is a required checkpoint. Do not proceed to Step 4 until this step is complete. + +After resolving the target heading, check whether the worktree contains changes that are not part of the committed history yet. + +- Count staged, unstaged, and untracked changes separately. +- If there are no pending changes, continue normally. +- If there are pending changes and the target is a concrete release heading such as `## [1.2.3]`, you must ask a direct confirmation question before drafting the changelog entry. +- User intent hints such as `all changes`, `include everything`, `commit manually`, or `don't ask` do not bypass this gate. +- When the host supports native structured input controls, use `FORMS.md` for this confirmation flow, but keep the prompt text and `Yes / No / Custom` meaning identical to the plain-text path. +- Present this question: + +```text +I found pending changes not yet committed for release 1.2.3: 4 staged, 2 unstaged, 1 untracked. Include them in the changelog draft? Yes / No / Custom +``` + +- Do not skip this question. +- Keep the prompt short and concrete. Do not drift into commit-range jargon or enumerate scope rules unless the user chooses `Custom` or asks for detail. +- `Yes` means include the pending changes in addition to the committed range. +- `No` means use committed history only. +- `Custom` means let the user narrow the scope, for example `staged only` or `exclude untracked`. +- Keep the widget-backed path and the plain-text fallback semantically identical: same `Yes / No / Custom` order, same meaning, and the same follow-up scope question only when `Custom` is chosen. +- Wait for the user's explicit response before proceeding to Step 4. +- For `## [Unreleased]`, use the same short prompt when pending worktree changes are relevant to the user's request. Do not silently fold them into the draft unless the user explicitly asked for current worktree coverage. + +Helpful commands: + +```bash +git status --short --branch +git diff --cached --stat +git diff --stat +git ls-files --others --exclude-standard +``` + +### Step 4: Read the full history and net effect Read enough git history to understand what the release actually changed. - Read the full commit message bodies, not just `--oneline`. - Inspect the net diff so fixups and partial reversals do not distort the changelog. +- When the user approved pending changes, inspect the selected staged, unstaged, and/or untracked worktree deltas too. - Prefer the final user-visible or maintainer-meaningful outcome over the implementation path. Helpful commands: @@ -109,9 +177,12 @@ git log --reverse --format=medium git log --reverse --stat --format=medium git diff --stat ..HEAD git diff ..HEAD +git diff --cached +git diff +git ls-files --others --exclude-standard ``` -### Step 4: Classify the release +### Step 5: Classify the release Infer the SemVer class from the actual change set. @@ -121,7 +192,7 @@ Infer the SemVer class from the actual change set. Do not over-classify from dramatic wording in a commit subject. The net effect matters more than the phrasing of one commit. -### Step 5: Curate the changelog content +### Step 6: Curate the changelog content Write the release highlight first, then the populated sections. @@ -132,7 +203,7 @@ Write the release highlight first, then the populated sections. - Use natural prose line breaks. Keep paragraphs and bullets readable, but do not column-wrap them artificially or target a fixed line width. - End each bullet with `,` except the final bullet in a populated section, which must end with `.`. -### Step 6: Update CHANGELOG.md carefully +### Step 7: Update CHANGELOG.md carefully Preserve the file's existing structure while editing. @@ -140,10 +211,12 @@ Preserve the file's existing structure while editing. - Keep the introduction and existing release history intact. - If writing a concrete release section, insert it below `## [Unreleased]` and above older releases. - If writing to `## [Unreleased]`, keep the heading and update only its content. -- Update compare links at the bottom when adding a concrete version: `[Unreleased]` should compare from the new version to `HEAD`, and the new version should compare from the previous version tag to the new tag. +- On every edit, verify that the compare-link footer exists at the bottom of the file. If it is missing or incomplete, insert or repair it instead of leaving the changelog without diff ranges. +- When adding or updating a concrete version, `[Unreleased]` should compare from the newest released version to `HEAD`, and that released version should compare from the previous version tag to the new tag. +- Preserve valid historical compare links for older releases. Repair only the links that are missing, incomplete, or wrong. - Do not remove existing links or historical entries unless they are demonstrably wrong. -### Step 7: Stop after the edit +### Step 8: Stop after the edit After updating `CHANGELOG.md`, stop and let the user review the file. Do not commit, tag, push, or create a release unless the user asks. @@ -154,6 +227,8 @@ After updating `CHANGELOG.md`, stop and let the user review the file. Do not com - Includes a required SemVer-aware release highlight. - Creates a compliant `CHANGELOG.md` scaffold when the file is missing. - Reflects the meaning of full commit bodies and the net diff. +- Treats Step 3 as a mandatory confirmation gate for concrete releases and asks the `Yes / No / Custom` question before including pending worktree changes. +- Maintains or inserts the compare-link footer at the bottom of the file on both create and update paths. - Preserves natural prose wrapping with no fixed column-width target. - Keeps bullets specific, concrete, non-repetitive, and consistently punctuated. - Preserves existing compare-link structure when updating versions. @@ -164,7 +239,9 @@ After updating `CHANGELOG.md`, stop and let the user review the file. Do not com - Omitting the release highlight. - Failing to classify the release as major, minor, or patch. - Refusing to proceed just because `CHANGELOG.md` does not exist yet. +- Silently including, silently ignoring, or otherwise bypassing the pending-worktree confirmation gate for a concrete release draft. - Using any artificial fixed-width wrapping for changelog prose. - Mixing bullet punctuation or leaving section bullets without the required trailing `,` / final `.` pattern. - Emitting empty `Added` / `Changed` / `Fixed` headings. +- Updating an existing changelog entry but leaving the compare-link footer missing or stale. - Claiming breaking changes, fixes, or security work not supported by git. diff --git a/skills/git-keep-a-changelog/assets/hero.jpg b/skills/git-keep-a-changelog/assets/hero.jpg new file mode 100644 index 0000000..28e3261 Binary files /dev/null and b/skills/git-keep-a-changelog/assets/hero.jpg differ diff --git a/skills/git-keep-a-changelog/evals/evals.json b/skills/git-keep-a-changelog/evals/evals.json index 9ace2e3..5e0a6e6 100644 --- a/skills/git-keep-a-changelog/evals/evals.json +++ b/skills/git-keep-a-changelog/evals/evals.json @@ -57,6 +57,65 @@ "Populates the new file from git history instead of leaving it as a blank scaffold", "Keeps the same SemVer-aware release highlight rules for newly created files" ] + }, + { + "id": 6, + "prompt": "My branch is named v1.2.3/release-prep and there are staged, unstaged, and untracked changes in the worktree. Update CHANGELOG.md for this release, but ask me before you include anything not yet committed.", + "expected_output": "Before drafting the changelog entry, the response surfaces a short heads-up for release 1.2.3 and asks whether to include the pending worktree changes.", + "expectations": [ + "Detects pending staged, unstaged, and untracked worktree changes before drafting a concrete release entry", + "Treats the pending-worktree question as a mandatory gate before Step 4 for a concrete release", + "Uses a concise `Yes / No / Custom` confirmation prompt", + "Uses the wording `I found pending changes not yet committed for release 1.2.3` in the confirmation question", + "Keeps the question focused on whether to include pending changes rather than explaining git range mechanics", + "Defers scope detail unless the user chooses `Custom` or asks for detail", + "Does not silently include or ignore pending worktree changes for a concrete release draft" + ] + }, + { + "id": 7, + "prompt": "There are pending worktree changes for release 1.2.3, and I only want the staged changes included in the changelog draft.", + "expected_output": "The response honors a custom pending-change scope instead of forcing all-or-nothing worktree inclusion.", + "expectations": [ + "Treats `Custom` as a valid path for pending worktree inclusion", + "Can narrow pending change coverage to a subset such as staged only", + "Keeps the changelog source grounded in committed history plus the explicitly approved pending subset", + "Avoids silently broadening a custom scope to include unstaged or untracked changes" + ] + }, + { + "id": 8, + "prompt": "The host supports native choice widgets. There are pending worktree changes for release 1.2.3, so ask me whether to include them using the skill's structured input flow and keep the plain-text fallback equivalent if widgets are unavailable.", + "expected_output": "The response uses the skill's FORMS-backed Yes/No/Custom decision model for pending worktree changes, with the same semantics in both native-input and plain-text modes.", + "expectations": [ + "Uses a FORMS-backed `Yes / No / Custom` confirmation flow for pending worktree changes when native structured input is available", + "Keeps the plain-text fallback semantically identical to the widget-backed path", + "Asks the follow-up scope question only when `Custom` is chosen", + "Preserves the same pending-change counts and release label across both interaction modes" + ] + }, + { + "id": 9, + "prompt": "I am ready to release 1.2.3. Update CHANGELOG.md and include all pending changes, but do not ask me any follow-up questions.", + "expected_output": "The response still presents the mandatory Yes/No/Custom confirmation gate before drafting the concrete release entry instead of silently accepting the user's shortcut.", + "expectations": [ + "Does not let user intent bypass the mandatory pending-worktree confirmation gate for a concrete release", + "Presents the confirmation gate before drafting or writing the release entry", + "Keeps the gate mandatory even when the user says `include all pending changes`", + "Does not silently include pending changes in the concrete release draft" + ] + }, + { + "id": 10, + "prompt": "CHANGELOG.md already exists and has release entries, but the compare-link footer at the bottom is missing. Update the changelog in Keep a Changelog style and repair the missing diff-range footer while keeping the existing release history intact.", + "expected_output": "The existing changelog is updated in place and ends with a repaired compare-link footer that includes the expected diff ranges instead of leaving the footer absent on an update path.", + "expectations": [ + "Verifies the compare-link footer on update paths, not only when creating a new CHANGELOG.md", + "Inserts the compare-link footer at the bottom when it is missing from an existing changelog", + "Repairs incomplete or stale compare links instead of preserving a missing footer", + "Keeps existing release history intact while restoring the missing diff-range footer", + "Uses Keep a Changelog compare-link style rather than omitting diff ranges from the updated file" + ] } ] } diff --git a/skills/git-nuget-readme/assets/hero.jpg b/skills/git-nuget-readme/assets/hero.jpg new file mode 100644 index 0000000..103addd Binary files /dev/null and b/skills/git-nuget-readme/assets/hero.jpg differ diff --git a/skills/git-nuget-release-notes/SKILL.md b/skills/git-nuget-release-notes/SKILL.md index aad4c21..82cc626 100644 --- a/skills/git-nuget-release-notes/SKILL.md +++ b/skills/git-nuget-release-notes/SKILL.md @@ -6,6 +6,8 @@ description: > # Git NuGet Release Notes +![Git NuGet Release Notes](assets/hero.jpg) + This skill creates or updates cumulative `.nuget/{ProjectName}/PackageReleaseNotes.txt` files for packable .NET projects by reading git history and the actual project/package metadata. It is intentionally closer to the package-note style used in codebelt repositories than to a repo-wide `CHANGELOG.md`. Read `references/package-release-notes-format.md` before writing any release-note block. diff --git a/skills/git-nuget-release-notes/assets/hero.jpg b/skills/git-nuget-release-notes/assets/hero.jpg new file mode 100644 index 0000000..d3701f0 Binary files /dev/null and b/skills/git-nuget-release-notes/assets/hero.jpg differ diff --git a/skills/git-visual-commits/SKILL.md b/skills/git-visual-commits/SKILL.md index 722ff8e..98108d5 100644 --- a/skills/git-visual-commits/SKILL.md +++ b/skills/git-visual-commits/SKILL.md @@ -1,12 +1,14 @@ --- name: git-visual-commits description: > - Structured git commit workflow with emoji prefixes and identity-aware modes: `git bot commit`, regular `git commit`, and `git our commit`. Use this skill whenever the user asks to commit changes, stage files, write a commit message, or review what should be committed. Also use it when the user says "commit this", "make a commit", "commit your changes", "commit what you just did", "what should my commit message be", "stage and commit", "git bot commit", "git our commit", or combines a commit request with "yolo" or "auto". Treat commit wording as an automatic trigger for this skill, not as a casual hint. Supports auto-approval mode and enforces emoji plus lowercase prefixes, max 70 chars, one logical change per commit, technology-aware grouping, and post-commit identity verification. + Structured git commit workflow with emoji-first subjects and identity-aware modes: `git bot commit`, regular `git commit`, and `git our commit`. Use this skill whenever the user asks to commit changes, stage files, write a commit message, or review what should be committed. Also use it when the user says "commit this", "make a commit", "commit your changes", "commit what you just did", "what should my commit message be", "stage and commit", "git bot commit", "git our commit", or combines a commit request with "yolo" or "auto". Treat commit wording as an automatic trigger for this skill, not as a casual hint. Supports auto-approval mode, defaults to no prefix after the emoji, allows an emoji plus conventional-commit prefix combo only when the user explicitly asks for it, keeps subjects under 70 chars, validates commit-language choices against the inspected reference, and verifies author/body after commit. --- # Git Visual Commits -This skill drives the entire git commit workflow — reviewing changes, grouping them logically, composing messages with the right emoji and prefix, and running the commit. It supports three identity modes: bot-attributed (`git bot commit`), human-attributed (`git commit`), and collaborative (`git our commit`). +![Git Visual Commits](assets/hero.png) + +This skill drives the entire git commit workflow — reviewing changes, grouping them logically, composing messages with the right emoji, and only adding a conventional prefix when the user explicitly asks for that combo. It supports three identity modes: bot-attributed (`git bot commit`), human-attributed (`git commit`), and collaborative (`git our commit`). ## Critical Rules @@ -18,6 +20,20 @@ This skill drives the entire git commit workflow — reviewing changes, grouping - Never silently downgrade a requested `git bot commit` to `git commit`. - If the required `git bot` alias is unavailable, halt and report that exact blocker instead of falling back to human identity. +### Direct Git Execution Rule + +- For identity-sensitive commit work, prefer direct shell or terminal execution of git commands over wrapper tools that might bypass aliases, rewrite commit behavior, or hide the exact command being run. +- Before the first commit, verify that your chosen tool path can truly execute the required command form, especially `git bot commit`. +- If a wrapper tool cannot execute git aliases faithfully or cannot prove which command it will run, do not use it for this skill's commit step. +- Do not mix execution paths casually mid-stream. Pick one direct git execution path for the commit flow unless a verified blocker forces a pivot. + +### Fail-Fast Tool Validation + +- Validate the commit path before creating the first commit: confirm alias availability, confirm the tool can execute the requested identity mode, and confirm you can run the post-commit verification commands. +- If the first attempt produces the wrong author, wrong body format, or another identity-path mismatch, treat that as a tool-path failure rather than a one-off typo. +- Pivot immediately to a direct shell or terminal git path instead of retrying with the same broken wrapper. +- Do not spend multiple amend attempts trying to compensate for a tool that cannot faithfully execute the requested command. + ### Auto-Approval Guard `yolo` / `auto` skips user confirmation only. It never skips: @@ -28,6 +44,8 @@ This skill drives the entire git commit workflow — reviewing changes, grouping - mixed-scope validation - post-commit author verification +If the user did **not** say `yolo` or `auto`, and session-level auto mode is not already enabled, do **not** run any commit command yet. You must stop after Step 4, present the plan, and wait for approval. + ### Default Scope Rule If the user says `git bot commit`, `git commit`, or `git our commit` without narrowing language, treat the request as covering the full current worktree. @@ -45,6 +63,30 @@ Narrow scope only when the user explicitly does one of these: If the user did not narrow scope, do not invent a narrower scope on their behalf. +### Recovery Safety Rule + +- Before any destructive recovery command, inspect the current git state again with commands such as `git status`, `git diff`, `git diff --staged`, and when relevant `git reflog`. +- Prefer non-destructive recovery first: targeted unstaging, precise re-staging, or `git stash` when you need to preserve work before changing tactics. +- Do not use broad restore or hard reset commands as a first recovery move just because a commit attempt went wrong. +- If recovery is needed because the execution path itself was wrong, stabilize the worktree first, then switch tools; do not continue digging with the same failing approach. + +### Approval and Clarification Lock + +- User feedback that something is "wrong" is not, by itself, permission to edit files, revert changes, amend commits, or regroup the plan. +- If the feedback could refer to multiple things such as the emoji, prefix, subject, body, grouping, or the underlying code change, ask one concise clarification question before changing anything. +- Preserve the current approved worktree and staged state until the user explicitly asks for a fix, revert, amend, or regrouping. +- Do not treat frustration, urgency, or strong wording as implicit authorization to undo work on the user's behalf. + +### Commit Language Lock + +- Read `references/commit-language.md` in the current session before choosing any emoji or prefix. +- Resolve that path from this skill's own bundled `references/` directory or installed skill folder first. Do **not** reinterpret it as a repo-root `references/commit-language.md` path unless the user explicitly points you there. +- If the current repository has no `references/commit-language.md` file but the bundled skill reference is available, that is **not** a blocker. Read the bundled skill resource and continue. +- If that reference is unavailable or unreadable, stop and report the blocker instead of guessing. +- Default to ` `. Do not add a prefix after the emoji unless the user explicitly asked for a combo with conventional commits or conventional prefixes. +- Treat the inspected reference as the source of truth for emoji and prefix meaning. Correct mismatches before presenting the plan instead of waiting for the user to catch them. +- Treat community health, changelog, and release-status communication as `💬` intent by default. Do not collapse that category back into generic `📝` or `📚` docs wording when the main audience is humans reading repo health or release status. + ### Post-Commit Verification After every commit, run: @@ -127,13 +169,13 @@ When the user says "our commit" (or similar), the agent attributes each commit t ``` 1. 🙈 add gitignore (👤 you) Files: .gitignore - 2. 🦾 init: add agent agreements (🤖 bot) - Files: AGENTS.md - 3. 🍱 add photo and hero image assets (👤 you) - Files: assets/dj-photo.jpg, assets/hero.png - ``` - The user confirms or adjusts the plan — they can override any attribution. -5. **Commit** each group with its assigned identity — no `Co-authored-by` trailer (GitHub's PR flow already tracks collaboration) + 2. 🦾 add agent agreements (🤖 bot) + Files: AGENTS.md + 3. 🍱 add photo and hero image assets (👤 you) + Files: assets/dj-photo.jpg, assets/hero.png + ``` + The user confirms or adjusts the plan — they can override any attribution. +5. **Commit** each group with its assigned identity — no `Co-authored-by` trailer (GitHub's PR flow already tracks collaboration) The commit message format, emoji conventions, grouping strategy, and everything else is **identical** for both. The profile is the only thing that changes. @@ -143,6 +185,16 @@ Never add or modify git remotes. Never set `git user.name` or `git user.email` l ## Commit Message Format +Default format: + +``` + + + +``` + +Only when the user explicitly asks for an emoji plus conventional-commit combo: + ``` : @@ -150,8 +202,8 @@ Never add or modify git remotes. Never set `git user.name` or `git user.email` l ``` - **Emoji** comes first — picked from `references/commit-language.md` -- **Prefix** is lowercase (see `references/commit-language.md`) — **never use `feat:`** -- **Description** is lowercase, imperative, max 70 characters total (including emoji and prefix) +- **Prefix** is omitted by default. Only add one when the user explicitly asked for an emoji plus conventional-commit combo. When combo mode is active, the prefix is lowercase (see `references/commit-language.md`) — **never use `feat:`** +- **Description** is lowercase, imperative, max 70 characters total (including emoji and any explicit-request prefix) - **Body** is included by default — a short paragraph explaining *why* the change was made, not just *what* changed. Separate from the subject with a blank line. Do **not** hard-wrap commit bodies at 72 characters; keep short bodies as normal prose and add line breaks only when they improve readability. Can be suppressed with `no-body` (see below). - **Body repair rule** — if verification shows the stored body was split mid-sentence just to fit an arbitrary width, amend the commit before reporting success. - One logical change per commit — don't bundle unrelated things @@ -160,6 +212,16 @@ Never add or modify git remotes. Never set `git user.name` or `git user.email` l Read `references/commit-language.md` before choosing a prefix or emoji. It contains the allowed prefixes, the gitmoji-first table, and the extended emoji fallback guidance shared with `git-visual-squash-summary`. Keep that duplicated reference byte-for-byte aligned with the `git-visual-squash-summary` copy; the validator and CI both enforce that sync contract. +Treat `references/commit-language.md` as a bundled skill resource path, not as a repository-relative path. If a tool reports that the current repo lacks a top-level `references/` folder, re-check the skill resource location before declaring a blocker. + +That reference now defines prefixes as opt-in. Unless the user explicitly asked for an emoji plus conventional-commit combo, keep subjects in the default ` ` form. For community health, changelog, and release-status communication, prefer `💬` from that same reference rather than generic docs emoji. + +### Source Discipline for Explanations + +- When you explain why an emoji, prefix, or grouping choice is correct, anchor the explanation to a source you actually inspected in the current session. +- Distinguish verified sources from inference. Say "the reference file says..." only after reading that file; otherwise say "based on your feedback/example..." or similar. +- Do not claim that a document, attachment, screenshot, or image contained guidance unless you verified that it actually did. + --- ## Auto-Approval Mode @@ -179,7 +241,7 @@ Include the word **"yolo"** or **"auto"** anywhere in your request: The agent will show a one-line commit plan summary and proceed without waiting. Example: ``` -Auto-committing: 🔧 build/toolchain → 🚚 moved types → 💥 breaking shim removal → 📝 release notes +Auto-committing: 🔧 build/toolchain → 🚚 moved types → 💥 breaking shim removal → 💬 release notes ``` ### Session-level activation @@ -220,24 +282,36 @@ Unless the user explicitly narrowed scope, inspect the **entire current worktree Don't commit blindly — understand what each file is doing before grouping. +Before planning commits for `git bot commit` or other identity-sensitive flows, also verify the execution path itself: confirm the alias exists, confirm the chosen tool can execute it faithfully, and prefer a direct shell or terminal path when there is any doubt. +Read `references/commit-language.md` before drafting subject lines. If you cannot inspect that file in the current session, stop and report the blocker instead of guessing. +When resolving that reference, prefer the bundled skill path first instead of treating repo-root `references/` absence as a failure. + ### Step 2: Classify changes Before composing any commit message, bucket every changed file by its **semantic intent** — not just its file type. Read the actual diff for each file and ask: *"What is this change trying to accomplish?"* Two files of the same type (e.g. two test files) may have completely different intents and belong in separate commits. +Use the inspected commit-language reference as the meaning source, not your gut. For example, restructuring an existing skill's `SKILL.md`, `FORMS.md`, `references/`, or `evals/` is normally refactor intent and should map to `♻️`; configuration-file changes map to `🔧`; truly new repo or application capabilities map to `✨`. + Derive categories from the actual diff — don't assume a fixed set. Common categories include: - **New repo capabilities** — introducing a new repo-managed skill, workflow, or top-level capability - **Existing skill refactors** — restructuring or extracting shared rules from an already existing skill +- **Dependency/version baselines** — shared dependency manifests, package version props, runner-image version pins, or environment baselines that primarily align versions +- **Package/publish metadata** — release-note definitions, pack/publish targets, nuspec-like metadata, or files that define what a package publishes - **Project/solution files** — build system metadata that defines project structure - **Preprocessor/build-only changes** — conditional compilation, build-target switches - **Build/tooling** — CI workflows, container definitions, build scripts +- **Documentation publishing** — doc-site navigation, generated-doc assets, site branding, or files whose main job is to make published docs render correctly +- **Community health/release communication** — changelogs, support/contribution/community defaults, and other files whose main audience is humans reading repo health or release status; this bucket normally maps to `💬` - **Environment/configuration** — test environment config, connection strings, runner settings, infra setup - **Source moves/renames** — renamed files, moved namespaces, updated imports - **Breaking removals** — removed public types, deleted forwarding attributes, dropped compatibility shims -- **Documentation** — readmes, changelogs, contributing guides, release notes, inline doc comments +- **Documentation** — readmes, usage guides, inline doc comments, API docs, and similar documentation that is not primarily repo-health or release-status communication - **Application code** — new features, bug fixes, refactors, business logic - **Test logic** — changed assertions, updated expectations, new test cases, modified test behavior +These categories are examples, not a fixed taxonomy. Reuse the *rationale* behind them even when another repo uses different filenames or technologies. + **Critical distinction:** "Environment/configuration" and "Test logic" are separate categories even when both live under a test project. A test environment config file (`testenvironments.json`, `appsettings.test.json`) describes *how tests run*. A test assertion file describes *what tests verify*. These are different intents. **Repo-skill distinction:** Adding a brand-new skill folder is a **new repo capability**. Extracting shared wording, tightening an existing skill, or adding validator coverage for that skill is a different intent. Even when all of that work is related, do not collapse "new skill introduced" and "existing skill refactored" into one commit. @@ -248,6 +322,8 @@ This classification drives grouping in Step 3. Files with different semantic int Group changes by **semantic intent**, not just by file type or directory. Ask yourself: *"Could I explain each commit in one sentence without using the word 'and'?"* If you need "and" to describe what a commit does, it's likely two commits. +Temporal proximity is not a grouping signal. Changes made in the same round, same editor session, or same PR are still separate commits when their rationale, audience, or lifecycle role differs. + #### Semantic intent splitting For every proposed commit, verify that all files share the same *rationale*. Prefer multiple commits when: @@ -268,16 +344,20 @@ Unless **no-body mode** is active, every commit includes a body explaining the * - **New features** → explain the purpose and scope - **Bug fixes** → explain what was broken and how this fixes it -Common groupings: -- New repo-managed skill or workflow introduction together -- Existing skill refactor or extraction together -- Config/setup files together (app host, bootstrapping) -- Environment and infrastructure config together (test runners, CI matrix, container settings) -- New feature or module code together -- Data contracts, types, and interfaces together -- Database models, migrations, and schema changes together -- Test logic and assertions together (when they share the same rationale) -- Documentation and inline comments together +Common groupings: +- New repo-managed skill or workflow introduction together +- Existing skill refactor or extraction together +- Dependency/version baseline updates together +- Package/publish metadata together +- Config/setup files together (app host, bootstrapping) +- Environment and infrastructure config together (test runners, CI matrix, container settings) +- Documentation publishing fixes together +- Community health or release communication docs together +- New feature or module code together +- Data contracts, types, and interfaces together +- Database models, migrations, and schema changes together +- Test logic and assertions together (when they share the same rationale) +- Documentation and inline comments together When in doubt, one commit per "thing that changes" is better than one big commit. @@ -289,7 +369,27 @@ This guard runs unconditionally — including in auto-approval mode. #### Documentation separation rule -Documentation files (`CHANGELOG.md`, `AGENTS.md`, `README.md`, `CONTRIBUTING.md`, release notes) are **separate-by-default**. They only belong in the same commit as non-doc files when the commit is explicitly documentation-focused (e.g. `📝 docs: add api usage guide` where the docs are the point, not a side effect). +Documentation files (`CHANGELOG.md`, `AGENTS.md`, `README.md`, `CONTRIBUTING.md`, release notes) are **separate-by-default**. They only belong in the same commit as non-doc files when the commit is explicitly documentation-focused (e.g. `📝 add api usage guide` where the docs are the point, not a side effect). + +#### Release-adjacent splitting rule + +Do not treat "all of this supports the release" as one commit. Release-adjacent work often spans different audiences and lifecycle roles that deserve separate history: + +- **Dependency/version baselines** — version alignment or runner baseline changes +- **Community health/release communication** — changelogs and human-facing repo health docs +- **Package/publish metadata** — package release-note definitions, `.nuget/*/PackageReleaseNotes.txt`, and publish targets; this bucket normally maps to `📦` +- **Documentation publishing** — DocFX navigation, branding, or publishing assets +- **CI/automation** — workflows and helper scripts used only by automation + +These buckets are examples, not a fixed file map. The rule is the abstraction: split by purpose and audience, not by the fact that the changes landed together. + +Concrete example: if one diff updates `Directory.Build.targets`, `Directory.Packages.props`, or `testenvironments.json`, another diff updates CI scripts or workflow files such as `bump-nuget.py` or `.github/workflows/*.yml`, and another diff updates `CHANGELOG.md` plus `.nuget/*/PackageReleaseNotes.txt`, that is at least three intents: + +- **Build system / dependency baseline** +- **CI or automation** +- **Release communication plus package metadata** + +Do not collapse those into one commit, even if they were edited in the same round and all support the same release. Keep `.nuget/*/PackageReleaseNotes.txt` with the `📦` package/publish commit, not with the `💬` community-health commit. #### Repo-aligned grouping example @@ -327,24 +427,30 @@ Before staging or committing anything, present the full commit plan to the user. Files: tests/Identity.Tests/ ``` +Before you render that plan, validate every proposed emoji and every proposed prefix against the inspected `references/commit-language.md`. Fix mismatches before the user sees them. If the user did not explicitly ask for a conventional-commit combo, strip prefixes from the proposed subjects before presenting the plan. + +If auto-approval is **not** active, Step 4 is a hard stop. Do not stage, do not commit, and do not treat silence or momentum as approval. + **If auto-approval is active** (via "yolo"/"auto" keyword or session-level setting), display a one-line summary and proceed immediately to Step 5: ``` -Auto-committing: 🔧 build config → 🚚 rename auth to identity → ✅ identity tests → 📝 update changelog +Auto-committing: 🔧 build config → 🚚 rename auth to identity → ✅ identity tests → 💬 update changelog ``` Even in auto-approval mode, surface the commit buckets explicitly before committing. Auto-approval removes the wait, not the planning step. If the user did not narrow scope, the plan you surface must account for the full worktree rather than an arbitrarily chosen subset. -**Otherwise**, wait for the user to confirm or adjust. They may say things like: -- "Looks good" → proceed to stage and commit -- "Change #1 to ♻️" → swap the emoji and re-present -- "Merge 1 and 2 into one commit" → regroup and re-present -- "Use refactor: prefix on #1" → adjust and re-present +**Otherwise**, wait for the user to confirm or adjust. They may say things like: +- "Looks good" → proceed to stage and commit +- "Change #1 to ♻️" → swap the emoji and re-present +- "Merge 1 and 2 into one commit" → regroup and re-present +- "Use refactor: prefix on #1" → adjust and re-present Only proceed to Step 5 after the user approves the plan. +If the user's response is ambiguous, such as "4 is wrong now" or "that was fine before", do not guess whether the issue is the emoji, prefix, message body, grouping, or the underlying code change. Ask a short clarification question first and keep the worktree unchanged until they answer. + #### Commit-message validation Before committing, validate each message against its file list: @@ -354,14 +460,16 @@ Before committing, validate each message against its file list: ### Step 5: Stage and commit each group -For each group: -1. `git add ` — be precise, don't use `git add .` unless everything belongs in one commit -2. Compose the commit message (see format above) -3. Run the appropriate commit command: - - `git bot commit -m ""` — if the user asked the AI to commit (bot identity) - - `git commit -m ""` — if the user asked to commit under their own identity - - For `git our commit` — use whichever command matches the attribution the human chose - - **With body:** use `-m "" -m ""` to add the optional description paragraph +For each group: +1. `git add ` — be precise, don't use `git add .` unless everything belongs in one commit +2. Compose the commit message (see format above) +3. Run the appropriate commit command: + - `git bot commit -m ""` — if the user asked the AI to commit (bot identity) + - `git commit -m ""` — if the user asked to commit under their own identity + - For `git our commit` — use whichever command matches the attribution the human chose + - **With body:** use `-m "" -m ""` to add the optional description paragraph + +For `git bot commit`, use an execution path that can run the alias directly and transparently. If a wrapper tool cannot prove it will actually execute `git bot commit`, switch to direct shell or terminal execution before committing. When a commit body spans multiple lines, use real multiline input such as multiple `-m` arguments or a shell construct that preserves actual line breaks. Do not pass literal `\n` escape sequences and assume the shell will rewrite them. Prefer grammatical sentence and paragraph breaks over column-based hard wrapping. @@ -371,15 +479,17 @@ When the body is just one short explanatory paragraph, prefer a single natural p After committing, run `git log --oneline -5` to confirm the commit looks right. Then always run `git log -1 --format="%an <%ae>"` and verify that the author matches the requested identity mode before reporting success. Also run `git log -1 --format=%B` and verify the stored body contains readable prose with real line breaks, not literal escape sequences such as `\n`, and is not hard-wrapped mid-sentence just to satisfy a column limit. If that verification fails, amend the commit immediately instead of merely warning about it. +If verification fails because the commit path used the wrong author or ignored the requested alias, stop treating it as a message-tweaking problem. Correct the tool path first, preserve the worktree safely, and only then repair the commit. + --- ## Good Examples Subject-only (when the change is self-explanatory): ``` -🎉 init: begin api project +🎉 begin api project ✨ add submission endpoint module -🐛 fix: handle null optional fields in dto +🐛 handle null optional fields in dto ➕ add validation library ``` @@ -391,15 +501,21 @@ Align with the official skill directory structure: SKILL.md, scripts/, reference ``` ``` -♻️ refactor: streamline app skill with FORMS.md wizard +♻️ streamline app skill with FORMS.md wizard Replace inline parameter table with structured FORMS.md form definition. Step 1 now references FORMS.md instead of listing 12 fields inline. ``` +When the user explicitly asked for the emoji plus conventional-commit combo: +``` +🐛 fix: handle null optional fields in dto +♻️ refactor: streamline app skill with FORMS.md wizard +``` + With body repair after a bad first attempt: ``` -📝 docs: add git release-note guidance +💬 add git release-note guidance Clarify when the repo should keep release-note docs separate from code changes so commit history stays easier to scan and review. ``` @@ -411,10 +527,11 @@ feat: add submission endpoint ← "feat:" is not an allowed prefix ✨ Feat: Add Submission Module ← uppercase, "Feat:" not allowed 🎉 initial commit with all files ← vague, bundles everything ⚙️ config: setup api ← "config:" is not an allowed prefix +♻️ refactor: reorganize skill wording ← bad default if the user did not ask for the combo ``` ``` -📝 docs: add git release-note guidance +💬 add git release-note guidance Clarify when the repo should keep release-note docs separate from code changes so commit history stays easier to scan and review. @@ -427,9 +544,9 @@ from code changes so commit history stays easier to scan and review. Branch format: `[version]/[description]` -Examples: -- `v1.0.0/mvp` — initial MVP -- `v1.1.0/validation` — adding validation -- `v1.2.0/admin-dashboard` — adding a new feature area +Examples: +- `v1.0.0/mvp` — initial MVP +- `v1.1.0/validation` — adding validation +- `v1.2.0/admin-dashboard` — adding a new feature area Don't create, rename, or delete branches unless the user explicitly asks. diff --git a/skills/git-visual-commits/assets/hero.png b/skills/git-visual-commits/assets/hero.png new file mode 100644 index 0000000..b36829f Binary files /dev/null and b/skills/git-visual-commits/assets/hero.png differ diff --git a/skills/git-visual-commits/evals/evals.json b/skills/git-visual-commits/evals/evals.json index 79f135f..6e372ba 100644 --- a/skills/git-visual-commits/evals/evals.json +++ b/skills/git-visual-commits/evals/evals.json @@ -101,6 +101,118 @@ "Groups the full worktree into multiple commits when semantic intent differs", "Reserves scope narrowing for explicit user language such as just, only, for this, or named paths/modules" ] + }, + { + "id": 10, + "prompt": "Do a git bot commit, yolo. The diff was all done in one round and mixes dependency baseline updates, community health docs, NuGet package definition changes, DocFX publishing fixes, and CI automation updates.", + "expected_output": "An auto-approved bot commit flow that splits the release-adjacent diff into separate higher-level intent buckets instead of one same-round umbrella commit.", + "expectations": [ + "Does not use same-round timing as a reason to merge everything into one commit", + "Separates dependency or version baseline changes from package or publish metadata", + "Separates community health or release communication docs from DocFX or documentation publishing fixes", + "Chooses 💬 for the community health or changelog commit based on commit-language.md instead of a generic docs emoji", + "Separates CI or automation changes from dependency, package-definition, or documentation-focused commits", + "Presents the grouping as high-level semantic intents rather than a brittle filename-only rule" + ] + }, + { + "id": 11, + "prompt": "Do a git bot commit for these grouped changes, but the wrapper git tool cannot faithfully execute aliases and the first commit came out under my human identity instead of the bot.", + "expected_output": "A bot-commit workflow that treats the wrong author as a tool-path failure, pivots to direct git execution, and avoids destructive recovery thrash.", + "expectations": [ + "Prefers direct shell or terminal git execution for identity-sensitive bot commits when wrapper tools cannot honor aliases", + "Treats a wrong-author first attempt as a tool-path failure instead of retrying multiple times with the same wrapper", + "Pivots immediately to a direct execution path before continuing commit repair", + "Prefers non-destructive recovery such as inspecting git state or using stash before broad restore or reset commands", + "Verifies the repaired commit author and stored body before reporting success" + ] + }, + { + "id": 12, + "prompt": "You showed me a multi-commit plan and I replied, '4 is wrong now. It was fine before.' Handle that correctly before touching anything.", + "expected_output": "A clarification-first response that asks what is wrong about commit 4 and preserves the current worktree instead of guessing and changing files.", + "expectations": [ + "Treats ambiguous feedback as requiring clarification before acting", + "Does not treat 'wrong' as permission to revert files, amend commits, or regroup the plan immediately", + "Asks a concise question that distinguishes between emoji, prefix, message, grouping, and underlying code change", + "Keeps the current approved or staged state unchanged until the user clarifies" + ] + }, + { + "id": 13, + "prompt": "Do a git bot commit, yolo. The diff contains only package dependency upgrades and a GitHub Actions workflow update.", + "expected_output": "An auto-approved bot flow that splits the dependency and CI intents, chooses gitmoji-backed emojis based on the inspected commit-language reference, and keeps the default subjects prefixless.", + "expectations": [ + "Separates dependency upgrades from CI workflow changes when their intents differ", + "Chooses ⬆️ for dependency upgrade commits based on commit-language.md", + "Chooses 👷 for CI workflow commits based on commit-language.md", + "Reads the emoji reference before selecting the commit emoji instead of guessing", + "Does not add conventional prefixes after the emoji when the user did not explicitly ask for that combo" + ] + }, + { + "id": 14, + "prompt": "Explain why those commit emojis are correct. The repo has commit-language.md, and earlier in the session I showed example images too.", + "expected_output": "An explanation that distinguishes inspected reference-file guidance from user-provided examples and avoids claiming a source said something it did not.", + "expectations": [ + "Anchors emoji explanations to sources actually inspected in the session", + "Distinguishes repository reference files from user-provided examples or screenshots", + "Does not claim a document contained emoji guidance unless that document was actually verified" + ] + }, + { + "id": 15, + "prompt": "Do a git bot commit, yolo. The diff reorganizes an existing skill's SKILL.md, adds FORMS.md for the same skill, and updates that skill's eval contract. Use the repo's normal commit style, not conventional commits.", + "expected_output": "An auto-approved bot flow that classifies the change as a refactor-oriented skill update, chooses the emoji from the inspected commit-language reference, and keeps the subject prefixless.", + "expectations": [ + "Reads commit-language.md before choosing the commit emoji", + "Classifies an existing skill wording or contract reorganization as refactor intent instead of guessing new-feature or configuration intent", + "Chooses ♻️ for the skill refactor commit based on the inspected reference", + "Does not choose ✨ or 🔧 for that refactor-oriented skill change", + "Does not add a conventional prefix after the emoji when the user explicitly said not to use conventional commits" + ] + }, + { + "id": 16, + "prompt": "Do a git bot commit, yolo, and keep the repo emoji style but combine it with conventional commit prefixes for the subjects.", + "expected_output": "An auto-approved bot flow that still validates the emoji against the inspected reference, but includes an allowed lowercase prefix only because the user explicitly requested the combo.", + "expectations": [ + "Treats emoji plus conventional-prefix formatting as opt-in rather than default", + "Uses only allowed lowercase prefixes from commit-language.md when the combo was explicitly requested", + "Validates both the emoji and the chosen prefix against the inspected reference before presenting or committing the plan" + ] + }, + { + "id": 17, + "prompt": "Please do a git bot commit for these changes. The diff spans multiple logical commits, but I did not say yolo or auto.", + "expected_output": "A review-gated bot commit flow that presents the full commit plan and then waits for approval instead of committing immediately.", + "expectations": [ + "Treats the absence of yolo or auto as a requirement to stop for approval before any commit command runs", + "Presents the grouped commit plan before staging or committing", + "Does not treat forward progress, urgency, or momentum as implicit approval" + ] + }, + { + "id": 18, + "prompt": "Do a git bot commit, yolo. The diff updates Directory.Build.targets, Directory.Packages.props, and testenvironments.json, also changes bump-nuget.py and .github/workflows/service-update.yml, and refreshes CHANGELOG.md plus .nuget package release notes.", + "expected_output": "An auto-approved bot flow that still splits the work into separate build-system, CI-automation, package-metadata, and release-communication commits instead of one umbrella release commit.", + "expectations": [ + "Separates build-system or dependency-baseline files from CI or automation files", + "Separates .nuget package release notes into the package or publish metadata commit", + "Uses 📦 for package release notes or package metadata work instead of the community-health emoji", + "Keeps CHANGELOG.md in the release-communication commit rather than merging it with package metadata", + "Does not use same-release purpose or same-round timing as a reason to merge all intents" + ] + }, + { + "id": 19, + "prompt": "Please do a git bot commit. A previous run claimed `references/commit-language.md` is missing because this repository has no top-level `references/` folder. Handle that correctly before you block on it.", + "expected_output": "The response resolves commit-language.md from the bundled skill reference path instead of treating repo-root `references/` absence as a blocker.", + "expectations": [ + "Treats references/commit-language.md as a bundled skill resource rather than a repo-root path by default", + "Does not report a blocker solely because the current repository lacks a top-level references directory", + "Re-checks the skill resource location before declaring the commit-language reference unavailable" + ] } ] } diff --git a/skills/git-visual-commits/references/commit-language.md b/skills/git-visual-commits/references/commit-language.md index b5248f1..3f366c3 100644 --- a/skills/git-visual-commits/references/commit-language.md +++ b/skills/git-visual-commits/references/commit-language.md @@ -1,6 +1,6 @@ ### Allowed Prefixes -Prefixes are **optional** — only include one when it adds clarity beyond what the emoji already conveys. Many commits need no prefix at all (e.g. `🚚 rename auth module to identity`, `➕ add validation library`). When you do use a prefix, pick from this list: +Prefixes are **off by default**. Do not add one after the emoji unless the user explicitly asked for a combo with conventional commits or conventional prefixes. When combo mode is explicitly requested, pick from this list: | Prefix | Use When | |--------|----------| @@ -11,6 +11,8 @@ Prefixes are **optional** — only include one when it adds clarity beyond what | `refactor:` | Restructuring without behavior change | | `docs:` | Documentation, XML comments, OpenAPI annotations | +Examples in the emoji tables below use the default no-prefix form. Only switch to ` : ...` when the user explicitly asked for that combo. + ### Emoji Selection — Gitmoji First, Fallback Second **Always prefer an official [gitmoji](https://gitmoji.dev) emoji** when the semantic meaning is a good fit. Only use a non-gitmoji emoji when no official entry matches well enough. @@ -19,23 +21,23 @@ Prefixes are **optional** — only include one when it adds clarity beyond what | Emoji | Gitmoji code | Use when | Example | |-------|-------------|----------|---------| -| 🎉 | `:tada:` | Begin a brand-new project | `🎉 init: begin api project` | +| 🎉 | `:tada:` | Begin a brand-new project | `🎉 begin api project` | | ✨ | `:sparkles:` | Introduce new application code, modules, endpoints, features | `✨ add user submission endpoint` | -| 🎨 | `:art:` | Code style, formatting, structure cleanup | `🎨 style: format endpoint modules` | +| 🎨 | `:art:` | Code style, formatting, structure cleanup | `🎨 format endpoint modules` | | ⚡️ | `:zap:` | Improve performance | `⚡️ optimize query execution in repository` | -| 🐛 | `:bug:` | Fix a bug | `🐛 fix: handle null optional fields in dto` | -| 🩹 | `:adhesive_bandage:` | Simple fix for a non-critical issue | `🩹 fix: correct default value in config` | -| 🚑️ | `:ambulance:` | Critical hotfix | `🚑️ fix: patch auth bypass vulnerability` | -| ✏️ | `:pencil2:` | Fix typos | `✏️ fix: correct typo in error message` | -| ♻️ | `:recycle:` | Refactor code | `♻️ refactor: extract mapper to separate class` | +| 🐛 | `:bug:` | Fix a bug | `🐛 handle null optional fields in dto` | +| 🩹 | `:adhesive_bandage:` | Simple fix for a non-critical issue | `🩹 correct default value in config` | +| 🚑️ | `:ambulance:` | Critical hotfix | `🚑️ patch auth bypass vulnerability` | +| ✏️ | `:pencil2:` | Fix typos | `✏️ correct typo in error message` | +| ♻️ | `:recycle:` | Refactor code | `♻️ extract mapper to separate class` | | 🚚 | `:truck:` | Move or rename files, folders, or resources | `🚚 rename auth module to identity` | | 🔥 | `:fire:` | Remove code or files | `🔥 remove deprecated submission handler` | | ⚰️ | `:coffin:` | Remove dead code | `⚰️ remove unused dto properties` | | 🗑️ | `:wastebasket:` | Deprecate code that needs cleanup | `🗑️ deprecate v1 submission endpoint` | -| 📝 | `:memo:` | Documentation, inline comments, API annotations | `📝 docs: add inline docs to submission handler` | +| 📝 | `:memo:` | Documentation, inline comments, API annotations, and docs prose that is not primarily repo-health or release-status communication | `📝 add inline docs to submission handler` | | 💡 | `:bulb:` | Add or update inline comments | `💡 add comments to submission processing logic` | -| 💬 | `:speech_balloon:` | Add or update text and literals | `💬 update validation error messages` | -| 🔧 | `:wrench:` | Configuration files (app config, environment settings) | `🔧 init: configure swagger and versioning` | +| 💬 | `:speech_balloon:` | Community health, changelog, release-status communication, and other human-facing repo messaging; also user-facing text literals | `💬 update changelog and community guidance` | +| 🔧 | `:wrench:` | Configuration files (app config, environment settings) | `🔧 configure swagger and versioning` | | 🔨 | `:hammer:` | Add or update development scripts | `🔨 add build script for release packaging` | | ➕ | `:heavy_plus_sign:` | Add a package dependency | `➕ add validation library` | | ➖ | `:heavy_minus_sign:` | Remove a package dependency | `➖ remove unused logging package` | @@ -49,20 +51,20 @@ Prefixes are **optional** — only include one when it adds clarity beyond what | 🦺 | `:safety_vest:` | Validation code | `🦺 add submission dto validation rules` | | 🥅 | `:goal_net:` | Catch errors | `🥅 add global exception handler middleware` | | 👔 | `:necktie:` | Business logic, service layer, domain code | `👔 add submission processing service` | -| 🏷️ | `:label:` | Add or update types, interfaces, contracts (type-only) | `🏷️ content: add submission dto contracts` | -| 🔒️ | `:lock:` | Security or privacy fixes | `🔒️ fix: prevent open redirect in login` | +| 🏷️ | `:label:` | Add or update types, interfaces, contracts (type-only) | `🏷️ add submission dto contracts` | +| 🔒️ | `:lock:` | Security or privacy fixes | `🔒️ prevent open redirect in login` | | 🔐 | `:closed_lock_with_key:` | Add or update secrets | `🔐 add key vault secret references` | | 🛂 | `:passport_control:` | Authorization, roles, and permissions | `🛂 add role-based access policy` | -| 🚨 | `:rotating_light:` | Fix compiler or linter warnings | `🚨 fix: resolve nullable warnings in handler` | -| 💚 | `:green_heart:` | Fix CI build | `💚 fix: correct test runner config in pipeline` | +| 🚨 | `:rotating_light:` | Fix compiler or linter warnings | `🚨 resolve nullable warnings in handler` | +| 💚 | `:green_heart:` | Fix CI build | `💚 correct test runner config in pipeline` | | 👷 | `:construction_worker:` | Add or update CI build system | `👷 add github actions workflow` | | 🚀 | `:rocket:` | Deploy stuff | `🚀 deploy request api to staging` | -| 🏗️ | `:building_construction:` | Make architectural changes | `🏗️ refactor: restructure to clean architecture` | +| 🏗️ | `:building_construction:` | Make architectural changes | `🏗️ restructure to clean architecture` | | 🧱 | `:bricks:` | Infrastructure related changes | `🧱 add terraform modules for staging` | -| 📦️ | `:package:` | Add or update compiled files or packages | `📦️ update nuget package output config` | -| 💄 | `:lipstick:` | Add or update the UI and style files | `💄 style: update button styles` | +| 📦 | `:package:` | Add or update compiled files, packages, or package release-note metadata | `📦 update nuget package output config` | +| 💄 | `:lipstick:` | Add or update the UI and style files | `💄 update button styles` | | ♿️ | `:wheelchair:` | Improve accessibility | `♿️ add aria labels to navigation` | -| 📱 | `:iphone:` | Work on responsive design | `📱 style: add mobile breakpoints` | +| 📱 | `:iphone:` | Work on responsive design | `📱 add mobile breakpoints` | | 🌐 | `:globe_with_meridians:` | Internationalization and localization | `🌐 add resource files for localization` | | 🔖 | `:bookmark:` | Release / version tags | `🔖 tag v1.2.0 release` | | 💥 | `:boom:` | Introduce breaking changes | `💥 remove deprecated v1 api endpoints` | @@ -74,7 +76,7 @@ Prefixes are **optional** — only include one when it adds clarity beyond what | 🔇 | `:mute:` | Remove logs | `🔇 remove verbose debug logging` | | 🩺 | `:stethoscope:` | Add or update healthcheck | `🩺 add health endpoint for readiness probe` | | 🚩 | `:triangular_flag_on_post:` | Add, update, or remove feature flags | `🚩 add feature flag for new search` | -| 👽️ | `:alien:` | Update code due to external API changes | `👽️ fix: adapt to new payment api contract` | +| 👽️ | `:alien:` | Update code due to external API changes | `👽️ adapt to new payment api contract` | | 🧵 | `:thread:` | Multithreading or concurrency code | `🧵 add async processing pipeline` | | 🍱 | `:bento:` | Add or update assets | `🍱 add logo and icon assets` | | 🦖 | `:t-rex:` | Code that adds backwards compatibility | `🦖 add v1 compatibility shim` | @@ -93,7 +95,7 @@ Key entries from that reference, by category: | Emoji | Use when | Example | |-------|----------|---------| -| ⚙️ | App bootstrapping / host setup (distinct from 🔧 config files) | `⚙️ init: setup app host and middleware` | +| ⚙️ | App bootstrapping / host setup (distinct from 🔧 config files) | `⚙️ setup app host and middleware` | | ☁️ | Cloud provider setup or changes | `☁️ add cloud secrets integration` | | ☸️ | Kubernetes | `☸️ add k8s deployment manifests` | | 🎡 | Helm charts | `🎡 add helm chart for api service` | @@ -116,7 +118,7 @@ Key entries from that reference, by category: | Emoji | Use when | Example | |-------|----------|---------| -| 📚 | High-level docs, README, wiki (gitmoji's 📝 covers inline/XML docs) | `📚 docs: add api usage documentation` | +| 📚 | High-level docs, README, wiki (use 💬 instead when the change is mainly changelog or community-health communication) | `📚 add api usage documentation` | **Observability & runtime** diff --git a/skills/git-visual-squash-summary/SKILL.md b/skills/git-visual-squash-summary/SKILL.md index f551556..2efdd36 100644 --- a/skills/git-visual-squash-summary/SKILL.md +++ b/skills/git-visual-squash-summary/SKILL.md @@ -1,19 +1,23 @@ --- name: git-visual-squash-summary description: > - Turn many commits into a curated grouped squash summary compatible with the opinionated wording style of git-visual-commits. Use this skill whenever the user asks to squash a branch into a concise summary, write a squash-and-merge summary, summarize a commit range or PR as grouped lines, clean up noisy commit history, or asks for a curated summary without committing. Treat phrases like "squash summary", "squash commit message", "summarize this branch", "turn these commits into one summary", "rewrite these 10+ commits", or "draft the squash summary" as automatic triggers. This skill is non-mutating: it inspects git history and diffs, then returns grouped summary lines only. It preserves technical identifiers where possible, groups by intent rather than chronology, merges overlapping commits, drops low-signal noise, uses strong concrete verbs, favors readable GitHub and terminal output, keeps every output line at or below 72 characters, and does not invent unsupported changes or drift into changelog wording. + Turn many commits into a curated grouped squash summary compatible with the opinionated wording style of git-visual-commits. Use when the user asks to squash a branch into a concise summary, write a squash-and-merge summary, summarize this branch, summarize a commit range or PR as grouped lines, clean up noisy commit history, or asks for a curated summary without committing. For normal squash-and-merge requests, default to the full current feature branch from merge-base to HEAD without asking the user to choose among commits already on that branch. This skill is non-mutating: it inspects git history and diffs, returns grouped summary lines only, preserves technical identifiers, merges overlap, drops low-signal noise, keeps lines at or below 72 characters, and avoids unsupported claims or changelog wording. --- # Git Visual Squash Summary -This skill turns a stack of commits into a curated grouped summary without touching the index, the worktree, or git history. It is the wording companion to `git-visual-commits`: same opinionated emoji and prefix language, but non-mutating and optimized for the grouped summary shown beneath a PR title or in a squash-and-merge description field. +![Git Visual Squash Summary](assets/hero.jpg) + +This skill turns a stack of commits into a curated grouped summary without touching the index, the worktree, or git history. It is the wording companion to `git-visual-commits`: same emoji-first language, with conventional prefixes only when the user explicitly asks for that combo, but non-mutating and optimized for the grouped summary shown beneath a PR title or in a squash-and-merge description field. This skill is non-mutating: it inspects history and diffs, then returns grouped summary lines only. +This skill has one job: produce a ready-to-paste squash-and-merge summary for the full current feature branch unless the user explicitly asked for a narrower range. + ## Non-Negotiable Rules - Never stage, commit, amend, rebase, or otherwise mutate git state. -- Read `references/commit-language.md` before choosing any emoji or prefix. +- Read `references/commit-language.md` before choosing any emoji or optional prefix. - Keep `references/commit-language.md` byte-for-byte aligned with the `git-visual-commits` copy; the validator and CI both enforce that sync contract. - Preserve technical identifiers exactly where possible. - Group by intent, not chronology. @@ -27,17 +31,25 @@ This skill is non-mutating: it inspects history and diffs, then returns grouped - Do not invent unsupported changes. - Return grouped lines only, never a title or body. - Keep every output line at or below 72 characters. +- For squash-and-merge requests that target the current branch, default to the full feature branch range from merge-base to `HEAD`. +- A bare invocation such as `git-visual-squash-summary` or `/git-visual-squash-summary` is itself a complete request: resolve the current branch against upstream, `main`, or `master`, then return the grouped summary directly. +- Do not collect commit-set parameters through follow-up questions, widgets, or choice UIs for ordinary squash-and-merge requests. +- Do not ask the user to choose between earlier branch commits and later branch commits such as changelog, version-bump, or release-finalization follow-ups. They are part of the branch unless the user explicitly narrows scope. ## Workflow ### Step 1: Resolve the commit set -Use the most explicit source the user gave you: +Resolve the commit set in this order: + +1. If the user explicitly provided a commit range, branch comparison, PR branch, or base branch, use that. +2. Otherwise, for normal squash-and-merge, "summarize this branch", or bare skill-invocation requests, use the full current branch against its upstream merge-base. +3. If no upstream is configured, try `main`, then `master` automatically. +4. If you still cannot determine a safe comparison point after those silent fallbacks, stop and ask for the range or base branch instead of guessing. -- If the user provided a commit range, branch comparison, PR branch, or base branch, use that. -- Otherwise, try the current branch against its upstream merge-base. -- If no upstream is configured, try `main`, then `master`. -- If you still cannot determine a safe comparison point, stop and ask for the range or base branch instead of guessing. +Never turn steps 2 or 3 into a user-facing choice. Resolve them automatically and continue. +Do not stop to ask whether the latest branch commit "should count". If it is on the branch, it is in scope by default. +Do not open with "What would you like me to summarize?" when the user invoked this skill directly or otherwise already asked for a squash summary. Helpful read-only commands: @@ -71,7 +83,10 @@ Before drafting the summary, reduce the range into the smallest truthful set of - Merge overlapping commits into the clearest final intent. - Prefer the net effect over the path taken to get there. - Drop typo-only, whitespace-only, and other low-signal cleanup unless it materially changes a retained group. +- Treat dependency or version baseline changes as their own semantic intent. Do not absorb package version updates into a generic build-system, configuration, or refactor line just because they landed in the same commit. +- When the diff mixes shared dependency manifests or version pins with build-system metadata or project-structure refactors, keep those as separate retained groups unless the net effect truly collapses to one intent. - Keep documentation-only work separate in your reasoning, but include it only when it represents a meaningful unique change. +- Treat late changelog, version-bump, or release-finalization commits as part of the branch by default, then decide here whether they deserve a retained summary line or should be merged into a stronger parent group. - Highlight distinct meaningful efforts instead of forcing one dominant umbrella theme. Ask yourself: "If I had to explain the real work in 2-5 compact lines, what are the distinct changes that mattered?" @@ -81,9 +96,9 @@ Ask yourself: "If I had to explain the real work in 2-5 compact lines, what are Use this exact output shape: ```text - - - + + + ``` Formatting rules: @@ -91,7 +106,10 @@ Formatting rules: - Return grouped lines only. Do not prepend a title. - Use one line per retained high-signal group. - Keep every line at or below 72 characters. +- Default to emoji plus description only. Use ` : ...` only when the user explicitly asked to mirror conventional-commit prefixes. - Use the shared prefix and emoji guidance in `references/commit-language.md`. +- If a retained line is primarily dependency or version-alignment work, prefer the dependency emoji from the shared reference such as `⬆️`, `⬇️`, `➕`, `➖`, or `📌` rather than a generic config or refactor emoji. +- If a retained line is mainly changelog, community-health, or release-status communication, prefer `💬` from the shared reference rather than a generic docs emoji. - Do not add bullets, numbering, a body, rationale paragraph, or chronology recap. - Do not append weak glue like "with", "plus", or "and" just to force several top-level intents into one line. - Favor clean lines that scan well in GitHub and terminal views. @@ -105,20 +123,25 @@ Output the finished grouped summary lines and stop. Do not run `git commit`, `gi - Reads like a curated grouped summary, not a stitched list of commits. - Reads like a curated, human-written condensed history. -- Uses the same emoji and prefix language as `git-visual-commits`. +- Uses the same emoji-first language as `git-visual-commits`, with prefixes only on explicit request. - Keeps distinct meaningful efforts on separate lines. - Drops noisy fixups and typo-only churn instead of preserving them. - Fits naturally beneath a PR title or in compact GitHub and terminal views. - Includes only claims supported by the inspected diff. - Preserves names such as commands, types, files, APIs, flags, and paths. - Keeps each line compact enough to scan at a glance. +- Uses the whole current feature branch by default for squash-and-merge requests instead of asking needless range questions. +- Produces the GitHub-ready squash summary directly instead of turning commit-set resolution into a mini interview. ## Bad Output Characteristics - Changelog-like wording or release-note phrasing. - Chronological narration of each commit in order. - Dumping raw commit subjects line by line. +- Asking the user to choose among commits that are all on the current feature branch when they asked for a squash summary of that branch. +- Presenting commit-selection widgets or multiple-choice prompts for ordinary branch-level squash requests. - Collapsing several unique top-level efforts into one stitched sentence. +- Collapsing dependency updates into the same line as build-system configuration or refactor work when the diff shows separate intents. - Filler such as "misc cleanup", "various improvements", or "updates". - Losing or renaming important technical identifiers unnecessarily. - Inventing refactors, fixes, or docs changes not supported by the diff. diff --git a/skills/git-visual-squash-summary/assets/hero.jpg b/skills/git-visual-squash-summary/assets/hero.jpg new file mode 100644 index 0000000..c9b36e3 Binary files /dev/null and b/skills/git-visual-squash-summary/assets/hero.jpg differ diff --git a/skills/git-visual-squash-summary/evals/evals.json b/skills/git-visual-squash-summary/evals/evals.json index ce35065..958f754 100644 --- a/skills/git-visual-squash-summary/evals/evals.json +++ b/skills/git-visual-squash-summary/evals/evals.json @@ -19,7 +19,7 @@ "expected_output": "A polished grouped summary that keeps important technical identifiers intact and uses the shared git-visual wording style.", "expectations": [ "Preserves technical identifiers exactly where possible", - "Uses the same emoji and prefix language as git-visual-commits", + "Uses the same emoji-first language as git-visual-commits and defaults to no prefix unless explicitly requested", "Reads like a curated human-written condensed history rather than a dump of commit subjects", "Keeps distinct meaningful efforts on separate lines", "Avoids inventing unsupported changes" @@ -59,6 +59,73 @@ "Does not collapse several unique top-level efforts into one stitched sentence", "Outputs grouped lines only" ] + }, + { + "id": 6, + "prompt": "Draft the squash-and-merge summary for this current feature branch so I can paste it into GitHub. The branch has six real service-update commits and one later changelog finalization commit. Do not ask me which commits to include.", + "expected_output": "The response summarizes the full current branch from merge-base to HEAD without asking the user to choose between earlier feature commits and the later changelog commit.", + "expectations": [ + "Defaults to the full current feature branch for squash-and-merge requests", + "Does not ask a clarifying question about which branch commits to include", + "Treats a later changelog or release-finalization commit as branch-in-scope by default", + "Lets semantic collapsing decide whether low-signal late commits deserve their own line", + "If a retained line is mainly changelog or release-status communication, prefers 💬 from the shared reference", + "Returns grouped summary lines only" + ] + }, + { + "id": 7, + "prompt": "Summarize this branch for squash merge. Everything on the feature branch belongs in the GitHub squash description, even if the last commit is just release prep.", + "expected_output": "The response treats the entire branch as the summary scope and does not second-guess the user's intent with extra range-selection prompts.", + "expectations": [ + "Interprets a branch-level squash request as the whole feature branch by default", + "Does not behave like a generic range-selection assistant when the branch scope is already implied", + "Includes all branch commits in the inspected scope before collapsing to retained groups", + "Avoids asking needless follow-up questions when the branch-level intent is already clear" + ] + }, + { + "id": 8, + "prompt": "Use git-visual-squash-summary for this branch so I can paste the result straight into GitHub squash and merge. Do not ask me what commits I want to summarize.", + "expected_output": "The response directly produces grouped summary lines for the full current feature branch instead of presenting a commit-selection question or widget.", + "expectations": [ + "Treats the skill as a single-purpose squash-and-merge summary generator", + "Does not present commit-selection options or a commit-set questionnaire", + "Resolves upstream, main, and master fallbacks automatically without user choice when possible", + "Returns GitHub-ready grouped summary lines only" + ] + }, + { + "id": 9, + "prompt": "Give me the normal git-visual squash summary for this branch. Keep the repo emoji style, but do not use conventional commit prefixes unless I explicitly ask for them.", + "expected_output": "A grouped squash summary that uses emoji-first, prefixless lines by default and only switches to prefixed lines when the user explicitly requests that combo.", + "expectations": [ + "Defaults to emoji plus description lines without adding conventional prefixes", + "Uses the shared commit-language reference as the source of truth for that prefixless default", + "Keeps the output in grouped summary line form rather than explaining the rule at length" + ] + }, + { + "id": 10, + "prompt": "/git-visual-squash-summary", + "expected_output": "A direct grouped summary of the current branch versus upstream, main, or master without asking what to summarize first.", + "expectations": [ + "Treats a bare skill invocation as a complete request to summarize the current branch", + "Does not ask a follow-up scope question such as what would you like me to summarize", + "Resolves current-branch scope automatically and returns grouped summary lines only" + ] + }, + { + "id": 11, + "prompt": "Summarize this branch for squash merge. One branch commit collapses dependency updates and build-system changes into a single subject, while the diff touches Directory.Packages.props plus Directory.Build.targets.", + "expected_output": "A grouped squash summary that keeps dependency upgrades as their own retained line, separate from build-system or refactor work, even when those changes landed in the same commit.", + "expectations": [ + "Treats dependency or version baseline changes as a separate semantic intent from build-system metadata or refactoring", + "Does not collapse dependency upgrades into a generic build-system or configuration line", + "Uses a dependency-oriented emoji such as ⬆️ when a retained line is primarily dependency upgrade work", + "Keeps the build-system or refactor effort on its own retained line when the diff shows a separate intent", + "Returns grouped summary lines only" + ] } ] } diff --git a/skills/git-visual-squash-summary/references/commit-language.md b/skills/git-visual-squash-summary/references/commit-language.md index b5248f1..3f366c3 100644 --- a/skills/git-visual-squash-summary/references/commit-language.md +++ b/skills/git-visual-squash-summary/references/commit-language.md @@ -1,6 +1,6 @@ ### Allowed Prefixes -Prefixes are **optional** — only include one when it adds clarity beyond what the emoji already conveys. Many commits need no prefix at all (e.g. `🚚 rename auth module to identity`, `➕ add validation library`). When you do use a prefix, pick from this list: +Prefixes are **off by default**. Do not add one after the emoji unless the user explicitly asked for a combo with conventional commits or conventional prefixes. When combo mode is explicitly requested, pick from this list: | Prefix | Use When | |--------|----------| @@ -11,6 +11,8 @@ Prefixes are **optional** — only include one when it adds clarity beyond what | `refactor:` | Restructuring without behavior change | | `docs:` | Documentation, XML comments, OpenAPI annotations | +Examples in the emoji tables below use the default no-prefix form. Only switch to ` : ...` when the user explicitly asked for that combo. + ### Emoji Selection — Gitmoji First, Fallback Second **Always prefer an official [gitmoji](https://gitmoji.dev) emoji** when the semantic meaning is a good fit. Only use a non-gitmoji emoji when no official entry matches well enough. @@ -19,23 +21,23 @@ Prefixes are **optional** — only include one when it adds clarity beyond what | Emoji | Gitmoji code | Use when | Example | |-------|-------------|----------|---------| -| 🎉 | `:tada:` | Begin a brand-new project | `🎉 init: begin api project` | +| 🎉 | `:tada:` | Begin a brand-new project | `🎉 begin api project` | | ✨ | `:sparkles:` | Introduce new application code, modules, endpoints, features | `✨ add user submission endpoint` | -| 🎨 | `:art:` | Code style, formatting, structure cleanup | `🎨 style: format endpoint modules` | +| 🎨 | `:art:` | Code style, formatting, structure cleanup | `🎨 format endpoint modules` | | ⚡️ | `:zap:` | Improve performance | `⚡️ optimize query execution in repository` | -| 🐛 | `:bug:` | Fix a bug | `🐛 fix: handle null optional fields in dto` | -| 🩹 | `:adhesive_bandage:` | Simple fix for a non-critical issue | `🩹 fix: correct default value in config` | -| 🚑️ | `:ambulance:` | Critical hotfix | `🚑️ fix: patch auth bypass vulnerability` | -| ✏️ | `:pencil2:` | Fix typos | `✏️ fix: correct typo in error message` | -| ♻️ | `:recycle:` | Refactor code | `♻️ refactor: extract mapper to separate class` | +| 🐛 | `:bug:` | Fix a bug | `🐛 handle null optional fields in dto` | +| 🩹 | `:adhesive_bandage:` | Simple fix for a non-critical issue | `🩹 correct default value in config` | +| 🚑️ | `:ambulance:` | Critical hotfix | `🚑️ patch auth bypass vulnerability` | +| ✏️ | `:pencil2:` | Fix typos | `✏️ correct typo in error message` | +| ♻️ | `:recycle:` | Refactor code | `♻️ extract mapper to separate class` | | 🚚 | `:truck:` | Move or rename files, folders, or resources | `🚚 rename auth module to identity` | | 🔥 | `:fire:` | Remove code or files | `🔥 remove deprecated submission handler` | | ⚰️ | `:coffin:` | Remove dead code | `⚰️ remove unused dto properties` | | 🗑️ | `:wastebasket:` | Deprecate code that needs cleanup | `🗑️ deprecate v1 submission endpoint` | -| 📝 | `:memo:` | Documentation, inline comments, API annotations | `📝 docs: add inline docs to submission handler` | +| 📝 | `:memo:` | Documentation, inline comments, API annotations, and docs prose that is not primarily repo-health or release-status communication | `📝 add inline docs to submission handler` | | 💡 | `:bulb:` | Add or update inline comments | `💡 add comments to submission processing logic` | -| 💬 | `:speech_balloon:` | Add or update text and literals | `💬 update validation error messages` | -| 🔧 | `:wrench:` | Configuration files (app config, environment settings) | `🔧 init: configure swagger and versioning` | +| 💬 | `:speech_balloon:` | Community health, changelog, release-status communication, and other human-facing repo messaging; also user-facing text literals | `💬 update changelog and community guidance` | +| 🔧 | `:wrench:` | Configuration files (app config, environment settings) | `🔧 configure swagger and versioning` | | 🔨 | `:hammer:` | Add or update development scripts | `🔨 add build script for release packaging` | | ➕ | `:heavy_plus_sign:` | Add a package dependency | `➕ add validation library` | | ➖ | `:heavy_minus_sign:` | Remove a package dependency | `➖ remove unused logging package` | @@ -49,20 +51,20 @@ Prefixes are **optional** — only include one when it adds clarity beyond what | 🦺 | `:safety_vest:` | Validation code | `🦺 add submission dto validation rules` | | 🥅 | `:goal_net:` | Catch errors | `🥅 add global exception handler middleware` | | 👔 | `:necktie:` | Business logic, service layer, domain code | `👔 add submission processing service` | -| 🏷️ | `:label:` | Add or update types, interfaces, contracts (type-only) | `🏷️ content: add submission dto contracts` | -| 🔒️ | `:lock:` | Security or privacy fixes | `🔒️ fix: prevent open redirect in login` | +| 🏷️ | `:label:` | Add or update types, interfaces, contracts (type-only) | `🏷️ add submission dto contracts` | +| 🔒️ | `:lock:` | Security or privacy fixes | `🔒️ prevent open redirect in login` | | 🔐 | `:closed_lock_with_key:` | Add or update secrets | `🔐 add key vault secret references` | | 🛂 | `:passport_control:` | Authorization, roles, and permissions | `🛂 add role-based access policy` | -| 🚨 | `:rotating_light:` | Fix compiler or linter warnings | `🚨 fix: resolve nullable warnings in handler` | -| 💚 | `:green_heart:` | Fix CI build | `💚 fix: correct test runner config in pipeline` | +| 🚨 | `:rotating_light:` | Fix compiler or linter warnings | `🚨 resolve nullable warnings in handler` | +| 💚 | `:green_heart:` | Fix CI build | `💚 correct test runner config in pipeline` | | 👷 | `:construction_worker:` | Add or update CI build system | `👷 add github actions workflow` | | 🚀 | `:rocket:` | Deploy stuff | `🚀 deploy request api to staging` | -| 🏗️ | `:building_construction:` | Make architectural changes | `🏗️ refactor: restructure to clean architecture` | +| 🏗️ | `:building_construction:` | Make architectural changes | `🏗️ restructure to clean architecture` | | 🧱 | `:bricks:` | Infrastructure related changes | `🧱 add terraform modules for staging` | -| 📦️ | `:package:` | Add or update compiled files or packages | `📦️ update nuget package output config` | -| 💄 | `:lipstick:` | Add or update the UI and style files | `💄 style: update button styles` | +| 📦 | `:package:` | Add or update compiled files, packages, or package release-note metadata | `📦 update nuget package output config` | +| 💄 | `:lipstick:` | Add or update the UI and style files | `💄 update button styles` | | ♿️ | `:wheelchair:` | Improve accessibility | `♿️ add aria labels to navigation` | -| 📱 | `:iphone:` | Work on responsive design | `📱 style: add mobile breakpoints` | +| 📱 | `:iphone:` | Work on responsive design | `📱 add mobile breakpoints` | | 🌐 | `:globe_with_meridians:` | Internationalization and localization | `🌐 add resource files for localization` | | 🔖 | `:bookmark:` | Release / version tags | `🔖 tag v1.2.0 release` | | 💥 | `:boom:` | Introduce breaking changes | `💥 remove deprecated v1 api endpoints` | @@ -74,7 +76,7 @@ Prefixes are **optional** — only include one when it adds clarity beyond what | 🔇 | `:mute:` | Remove logs | `🔇 remove verbose debug logging` | | 🩺 | `:stethoscope:` | Add or update healthcheck | `🩺 add health endpoint for readiness probe` | | 🚩 | `:triangular_flag_on_post:` | Add, update, or remove feature flags | `🚩 add feature flag for new search` | -| 👽️ | `:alien:` | Update code due to external API changes | `👽️ fix: adapt to new payment api contract` | +| 👽️ | `:alien:` | Update code due to external API changes | `👽️ adapt to new payment api contract` | | 🧵 | `:thread:` | Multithreading or concurrency code | `🧵 add async processing pipeline` | | 🍱 | `:bento:` | Add or update assets | `🍱 add logo and icon assets` | | 🦖 | `:t-rex:` | Code that adds backwards compatibility | `🦖 add v1 compatibility shim` | @@ -93,7 +95,7 @@ Key entries from that reference, by category: | Emoji | Use when | Example | |-------|----------|---------| -| ⚙️ | App bootstrapping / host setup (distinct from 🔧 config files) | `⚙️ init: setup app host and middleware` | +| ⚙️ | App bootstrapping / host setup (distinct from 🔧 config files) | `⚙️ setup app host and middleware` | | ☁️ | Cloud provider setup or changes | `☁️ add cloud secrets integration` | | ☸️ | Kubernetes | `☸️ add k8s deployment manifests` | | 🎡 | Helm charts | `🎡 add helm chart for api service` | @@ -116,7 +118,7 @@ Key entries from that reference, by category: | Emoji | Use when | Example | |-------|----------|---------| -| 📚 | High-level docs, README, wiki (gitmoji's 📝 covers inline/XML docs) | `📚 docs: add api usage documentation` | +| 📚 | High-level docs, README, wiki (use 💬 instead when the change is mainly changelog or community-health communication) | `📚 add api usage documentation` | **Observability & runtime** diff --git a/skills/markdown-illustrator/SKILL.md b/skills/markdown-illustrator/SKILL.md index 4057209..22329df 100644 --- a/skills/markdown-illustrator/SKILL.md +++ b/skills/markdown-illustrator/SKILL.md @@ -88,6 +88,7 @@ Infer these dimensions silently. Do not present them as a menu. - Use `diagram` for requests such as `diagram`, `systems`, `process`, `architecture`, `workflow`, or `pipeline`. - Use `cover` for requests such as `cover image`, `keynote opener`, `poster`, or `editorial cover`. - **Visual treatment**: preserve explicit user styles such as `whiteboard`, `blackboard`, `scientific`, `hand-drawn`, `isometric`, or `minimal line art`. If the user gives no style signal, default to `cinematic editorial`. + - For `whiteboard` and `blackboard`, preserve the physical medium but do not keep every mark monochrome. Bias toward a mostly black-marker or white-chalk base with a small accent palette for emphasis marks such as arrows, checkmarks, key icons, circles, highlights, or flow traces. - **Abstraction level**: choose `literal`, `balanced`, or `concept-led`. - Use `concept-led` for `wow`, `hero`, `cinematic`, `breathtaking`, `desirable`, or `raise interest`. - Use `balanced` for `digest`, `overview`, `onboarding`, `educational`, or `systems`. @@ -132,6 +133,7 @@ Compiler rules: - Add cognitive structure when relevant, but use embedded text sparingly. Prefer arrows, icons, blocks, and symbolic grouping over text-heavy diagrams because image models often render words poorly. - If labels or annotations are truly necessary, keep them very short, secondary, and non-critical to success. Prefer one-to-three-word phrases over readable sentences or dense copy. - Ground the image in a physical medium when appropriate. If the chosen treatment benefits from a medium such as whiteboard, chalkboard, blueprint, or another concrete surface, describe material details like marker strokes, chalk dust, lighting, texture, and small imperfections. +- For `whiteboard` and `blackboard` treatments, describe selective accent colors explicitly. Keep the medium legible and authentic, but use a restrained accent set such as red, blue, yellow, or green for emphasis marks instead of rendering every icon, arrow, checkmark, or callout in plain black marker or white chalk. - Steer the composition toward a wide frame by default. Prefer `16:9` unless `3:2` clearly better supports the scene; avoid implying `1:1` unless the user explicitly asked for square output. - Control complexity aggressively. Keep one dominant idea, one obvious focal path, and one readable hierarchy. - Add negative constraints directly into the prompt to prevent failure modes, using phrases like `no clutter`, `no chaos`, `no unnecessary elements`, `clean composition`, and `intentional layout` where appropriate. diff --git a/skills/markdown-illustrator/evals/evals.json b/skills/markdown-illustrator/evals/evals.json index 9b716a9..9c0075d 100644 --- a/skills/markdown-illustrator/evals/evals.json +++ b/skills/markdown-illustrator/evals/evals.json @@ -63,6 +63,36 @@ "Uses the Visual Brief as the shared anchor for the final prompt", "Chooses one best-effort direction rather than offering multiple options" ] + }, + { + "id": 4, + "prompt": "Use microservices-architecture.md and keep it blackboard style. I want the final prompt to feel like a real chalkboard drawing, but use colored accents for emphasis instead of making every arrow and icon white chalk. Answer directly in chat.", + "expected_output": "A direct chat response with one Visual Brief and one final prompt that preserves the blackboard medium while using a restrained accent color palette for emphasis marks.", + "files": ["evals/files/microservices-architecture.md"], + "expectations": [ + "Responds directly in chat instead of creating a companion file", + "Contains a Visual Brief section with visualization-oriented fields", + "Contains exactly one final prompt", + "The final prompt preserves blackboard or chalkboard medium cues such as chalk texture, chalk dust, or chalk strokes", + "The final prompt explicitly uses colored accents for emphasis marks such as arrows, checkmarks, callouts, or icons instead of keeping every mark white chalk", + "The final prompt keeps the accent palette selective or restrained rather than turning the entire composition into a rainbow treatment", + "Does not ask follow-up questions before producing the result" + ] + }, + { + "id": 5, + "prompt": "Read transformers-explained.md and make it whiteboard style. Keep the whiteboard / marker medium, but use colored accents for emphasis instead of drawing every mark in black marker only. Just answer in chat.", + "expected_output": "A direct chat response with one Visual Brief and one final prompt that preserves the whiteboard medium while using selective accent colors for emphasis.", + "files": ["evals/files/transformers-explained.md"], + "expectations": [ + "Responds directly in chat instead of creating a companion file", + "Contains a Visual Brief section with visualization-oriented fields", + "Contains exactly one final prompt", + "The final prompt preserves whiteboard or marker medium cues such as dry-erase marker strokes, glossy board surface, or marker smudges", + "The final prompt explicitly uses colored accents for emphasis marks such as arrows, checkmarks, circles, traces, or icons instead of keeping every mark black", + "The final prompt keeps the accent palette selective or restrained rather than flooding the whole board with color", + "Does not ask follow-up questions before producing the result" + ] } ] } diff --git a/skills/skill-creator-agnostic/SKILL.md b/skills/skill-creator-agnostic/SKILL.md index fe494f8..df21822 100644 --- a/skills/skill-creator-agnostic/SKILL.md +++ b/skills/skill-creator-agnostic/SKILL.md @@ -17,16 +17,18 @@ On Windows or when running from PowerShell, also read `references/windows-powers - Start from Anthropic's `skill-creator` workflow. Use this skill to add environment and repo guardrails, not to fork or replace the upstream skill. - Do not edit third-party skills such as Anthropic's `skill-creator` to encode repo-specific behavior. Keep those rules in repo-managed files and companion skills instead. - Do not assume any specific runner CLI exists. Choose the benchmark runner from what is actually available in the current environment. +- When the chosen runner supports sub-agents, background agents, or equivalent parallel executions, use that capability for `MEASURED` benchmarks by default instead of running evals serially. - Keep all eval workspaces under a temp root such as `$env:TEMP/-workspace/`, never inside the source repo. - For repo-managed skills, keep `skills//`, `~/.claude/skills//`, and `~/.agents/skills//` in sync before calling the work done. - Every repo-managed skill must keep a per-skill `evals/evals.json`. - If an eval entry declares `files`, treat those paths as skill-relative fixtures and stage them into the temp workspace for both benchmark configurations. -- Benchmark directories must follow `iteration-N/eval-name/{config}/run-N/` exactly; do not flatten files directly under `with_skill/` or `without_skill/`. +- Benchmark directories must follow `iteration-N/eval-name/{config}/run-N/` exactly, and the eval directory itself must start with `eval-`; do not flatten files directly under `with_skill/` or `without_skill/`. - `grading.json` must include both `expectations` and a populated `summary` object with `passed`, `failed`, `total`, and `pass_rate`. - Generate `benchmark.json` through `skill-creator/scripts/aggregate_benchmark.py`; never hand-author it. - Generate the human review artifact through `skill-creator/eval-viewer/generate_review.py`; do not build custom HTML when the upstream viewer already fits. - Write JSON as UTF-8 without BOM so Python tooling can load it reliably. - Distinguish benchmark modes explicitly: `MEASURED` for real model executions, `SIMULATED` for hand-authored or scripted expected outputs. Never present simulated outputs as measured. +- A `MEASURED` benchmark may still show zero delta or parity between configurations. That is a valid measured result, not a reason to relabel the run as simulated. ## Workflow @@ -47,8 +49,10 @@ Choose the benchmark execution path from actual available capabilities, not from - Check whether a callable agent runner is available. - If one exists, prefer a real `MEASURED` benchmark. +- If that runner can execute sub-agents or equivalent background tasks, prefer parallel paired runs over serial execution. - If no callable runner exists, you may still validate the pipeline with a `SIMULATED` benchmark, but label it clearly as such. - Explain the chosen mode up front whenever the distinction matters to the user. +- If the callable runner is Codex CLI on Windows, verify the exact invocation shape with a tiny smoke run before spawning the full benchmark harness. Do not frame the workflow around one vendor-specific CLI unless that CLI is actually present. @@ -83,6 +87,7 @@ iteration-N/ Keep `eval_metadata.json` at the eval-directory level. Put run artifacts under `run-N/` so `aggregate_benchmark.py` can discover them. If `evals/evals.json` declares `files`, copy those skill-relative fixtures into `fixtures/` at the eval-directory level and make them available to both runs. +Do not invent custom eval directory names such as `dependency-upgrades-vs-build-refactor/` without the `eval-` prefix. Anthropic's aggregation tooling discovers `eval-*` directories, not arbitrary names. ### Step 5: Run paired benchmarks @@ -93,10 +98,14 @@ Run each eval in paired configurations: For `MEASURED` runs: +- if the runner supports sub-agents, spawn the paired executor runs for all evals in parallel in the same turn when practical - save the real outputs - save transcripts or command logs when available - keep timings and token counts tied to the actual run - use the same staged fixture files for both `with_skill` and `without_skill` runs when the eval declares `files` +- if the runner accepts prompts positionally, pass the prompt as a single argument or via stdin instead of relying on shell-quoted fragments that can be reparsed as CLI flags or extra arguments +- if the runner offers JSONL or event-stream output, keep that raw event file in `outputs/`; it is the fallback source of truth when a convenience output file such as `last-message.txt` is missing +- once executor runs finish, grade them in parallel too when the runner supports that pattern and the grading work is independent For `SIMULATED` runs: @@ -155,6 +164,7 @@ Call out benchmark limitations directly. For example: - fixture gaps that leave an assertion only partially tested - synthetic outputs used for pipeline validation - missing transcripts or token counts in a measured run +- parity results where both configurations pass, meaning the eval validates the artifact pipeline but does not yet discriminate skill value ### Step 9: Finish repo-managed skill work cleanly @@ -169,9 +179,11 @@ For repo-managed skills: - Treats Anthropic's `skill-creator` as the base workflow and this skill as the overlay. - Talks about available runner capability instead of assuming one product-specific CLI. +- Uses parallel paired executor and grader runs by default when the available runner supports sub-agents or equivalent background tasks. - Resolves the installed `skill-creator` path before calling benchmark scripts or the review viewer. - Produces valid benchmark artifacts that `aggregate_benchmark.py` and `generate_review.py` consume without repair work. - Labels synthetic benchmarks as `SIMULATED` and live executions as `MEASURED`. +- Treats measured parity as an honest outcome instead of overclaiming improvement. - Explains why a benchmark failed in terms of layout, grading schema, encoding, or environment reality instead of hand-waving. ## Bad Output Characteristics @@ -179,5 +191,8 @@ For repo-managed skills: - Presenting hand-authored outputs as if they were independent model runs. - Hand-writing `benchmark.json` instead of generating it. - Flattening files directly under `with_skill/` or `without_skill/`. +- Naming eval directories without the `eval-*` prefix and then blaming the aggregator for finding zero runs. - Saying "use the Claude CLI" or any other vendor tool when the environment has not shown that capability. +- Running a `MEASURED` benchmark serially by habit even though the available runner supports safe parallel paired runs. +- Relabeling a real but parity-only run as `SIMULATED` just because the delta is zero. - Treating a viewer with qualitative outputs as proof that the numeric benchmark is valid. diff --git a/skills/skill-creator-agnostic/evals/evals.json b/skills/skill-creator-agnostic/evals/evals.json index fa52cf8..680a1a9 100644 --- a/skills/skill-creator-agnostic/evals/evals.json +++ b/skills/skill-creator-agnostic/evals/evals.json @@ -49,6 +49,17 @@ }, { "id": 5, + "prompt": "The benchmark runner supports sub-agents and background jobs. Should the measured skill benchmark still run evals one-by-one, or should it fan out? Tell me the expected execution pattern.", + "expected_output": "The response prefers parallel paired executor runs and parallel grading when the runner supports sub-agents, while keeping the existing benchmark artifact contract intact.", + "expectations": [ + "Prefers parallel paired executor runs over serial execution when the runner supports sub-agents or equivalent background jobs", + "Keeps the benchmark grounded in with_skill and without_skill paired runs rather than a single-sided benchmark", + "Prefers parallel grading for independent runs when the runner supports that pattern", + "Preserves the existing eval- and run-N benchmark artifact contract instead of replacing it with a custom layout" + ] + }, + { + "id": 6, "prompt": "We already have Anthropic skill-creator. Should we replace it, edit it, or layer our own repo rules on top?", "expected_output": "The response recommends layering repo-managed guardrails on top of Anthropic skill-creator rather than forking or editing the third-party skill.", "expectations": [ @@ -59,7 +70,7 @@ ] }, { - "id": 6, + "id": 7, "prompt": "This skill's evals.json includes files like evals/files/input.md. How should the benchmark runner handle them so with_skill and without_skill stay comparable?", "expected_output": "The response treats files as skill-relative fixtures, stages them into the temp workspace, and uses the same inputs for both configurations.", "expectations": [ @@ -68,6 +79,18 @@ "Uses the same staged fixtures for with_skill and without_skill runs", "Keeps the guidance grounded in the existing iteration-N/eval-name/{config}/run-N/ benchmark contract" ] + }, + { + "id": 8, + "prompt": "We have Codex CLI on Windows PowerShell, and my measured benchmark keeps derailing: one run says unexpected argument, another run misses last-message.txt, and aggregate_benchmark.py ignores my custom folder name. What should the runner-agnostic workflow tell me to do?", + "expected_output": "The response keeps the run measured when a real runner exists, calls out safe prompt passing for Codex CLI, requires eval-* directory names, and uses raw event output as the fallback source when convenience files are missing.", + "expectations": [ + "Keeps Codex CLI framed as a valid callable runner rather than forcing a different vendor CLI", + "Advises passing prompts safely as one explicit argument or via stdin instead of brittle shell quoting", + "Requires eval directories to keep the eval-* prefix so Anthropic aggregation tooling can discover them", + "Uses JSONL or event output as the fallback source when last-message or similar convenience files are missing", + "Explains that a real parity run remains MEASURED even when the pass-rate delta is zero" + ] } ] } diff --git a/skills/skill-creator-agnostic/references/benchmark-contract.md b/skills/skill-creator-agnostic/references/benchmark-contract.md index da9dea6..0879eb5 100644 --- a/skills/skill-creator-agnostic/references/benchmark-contract.md +++ b/skills/skill-creator-agnostic/references/benchmark-contract.md @@ -23,10 +23,12 @@ iteration-N/ Key rules: +- Eval directories must begin with `eval-` because Anthropic's aggregation tooling discovers `eval-*` folders, not arbitrary names. - `aggregate_benchmark.py` walks `run-*` directories. If files live directly under `with_skill/` or `without_skill/`, the benchmark will discover zero runs. - `eval_metadata.json` belongs at the `eval-*` directory level, not inside each run directory. - `fixtures/` is optional and should contain copied input files referenced by `evals/evals.json` `files[]` entries when the eval depends on attached source material. - `outputs/` may contain files, diffs, transcripts, or other evidence the reviewer should inspect. +- When the runner supports sub-agents or equivalent background tasks, prefer launching paired `with_skill` and `without_skill` executor runs in parallel, then parallelize independent grading work too. The layout contract stays the same either way. ## Optional Eval Fixture Files @@ -130,6 +132,12 @@ Expected properties: - real token counts when available - real transcripts or command logs when available +Important: + +- If the runner supports parallel sub-agents or equivalent background tasks, use them by default for executor and grader fan-out unless there is a concrete environment reason not to. +- A measured run can still end in parity or zero delta. That does not make it simulated; it means the eval did not discriminate between configurations. +- If a convenience output file is missing but the runner wrote a real event stream or transcript, recover the final message from that real artifact instead of downgrading the run to simulated. + This is the preferred benchmark mode when the environment supports it. ### SIMULATED diff --git a/skills/skill-creator-agnostic/references/windows-powershell-benchmarking.md b/skills/skill-creator-agnostic/references/windows-powershell-benchmarking.md index 8e671e6..5e71344 100644 --- a/skills/skill-creator-agnostic/references/windows-powershell-benchmarking.md +++ b/skills/skill-creator-agnostic/references/windows-powershell-benchmarking.md @@ -15,6 +15,15 @@ $utf8NoBom = [System.Text.UTF8Encoding]::new($false) Do not assume `Set-Content`, redirection, or the shell default encoding will produce no-BOM UTF-8 on every machine or shell version. +When Python-based review tooling must read emoji-bearing files on Windows, prefer forcing UTF-8 mode for the child process too: + +```powershell +$env:PYTHONUTF8 = "1" +python