From 7203881a4de85993ba6759d34d298dcca37f006f Mon Sep 17 00:00:00 2001 From: "aicia[bot]" Date: Mon, 16 Mar 2026 22:13:39 +0100 Subject: [PATCH 01/23] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20refactor:=20extract?= =?UTF-8?q?=20git=20visual=20commit=20language?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Move the shared prefix and emoji guidance for git-visual-commits into a dedicated reference so the existing commit workflow keeps one maintained wording source. --- skills/git-visual-commits/SKILL.md | 165 ++---------------- .../references/commit-language.md | 156 +++++++++++++++++ 2 files changed, 169 insertions(+), 152 deletions(-) create mode 100644 skills/git-visual-commits/references/commit-language.md diff --git a/skills/git-visual-commits/SKILL.md b/skills/git-visual-commits/SKILL.md index 8884314..e517225 100644 --- a/skills/git-visual-commits/SKILL.md +++ b/skills/git-visual-commits/SKILL.md @@ -146,159 +146,20 @@ Never add or modify git remotes. Never set `git user.name` or `git user.email` l ``` -- **Emoji** comes first — picked from the technology/type tables below -- **Prefix** is lowercase (see allowed prefixes below) — **never use `feat:`** -- **Description** is lowercase, imperative, max 70 characters total (including emoji and prefix) +- **Emoji** comes first — picked from the technology/type tables below +- **Prefix** is lowercase (see allowed prefixes below) — **never use `feat:`** +- **Description** is lowercase, imperative, max 70 characters total (including emoji and 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). -- One logical change per commit — don't bundle unrelated things - -### 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: - -| Prefix | Use When | -|--------|----------| -| `init:` | Initial setup or configuration of something new | -| `content:` | Endpoint definitions, DTOs, contracts, data shapes | -| `style:` | Code formatting, cleanup, aesthetic changes | -| `fix:` | Bug fixes | -| `refactor:` | Restructuring without behavior change | -| `docs:` | Documentation, XML comments, OpenAPI annotations | - -### 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. - -#### Primary: Gitmoji - -| Emoji | Gitmoji code | Use when | Example | -|-------|-------------|----------|---------| -| 🎉 | `:tada:` | Begin a brand-new project | `🎉 init: 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` | -| ⚡️ | `: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` | -| 🚚 | `: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` | -| 💡 | `: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` | -| 🔨 | `: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` | -| ⬆️ | `:arrow_up:` | Upgrade package dependencies | `⬆️ upgrade dependencies to latest` | -| ⬇️ | `:arrow_down:` | Downgrade dependencies | `⬇️ downgrade ef core to stable release` | -| 📌 | `:pushpin:` | Pin dependencies to specific versions | `📌 pin node version to 20 lts` | -| 🗃️ | `:card_file_box:` | Database changes, ORM models, migrations, entities | `🗃️ add submission entity and db context` | -| 🌱 | `:seedling:` | Add or update seed files | `🌱 add initial request table migration` | -| ✅ | `:white_check_mark:` | Add or update tests | `✅ add integration tests for submission api` | -| 🧪 | `:test_tube:` | Add a failing test (TDD red phase) | `🧪 add failing test for null notes field` | -| 🦺 | `: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` | -| 🔐 | `: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` | -| 👷 | `: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` | -| 🧱 | `: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` | -| ♿️ | `:wheelchair:` | Improve accessibility | `♿️ add aria labels to navigation` | -| 📱 | `:iphone:` | Work on responsive design | `📱 style: 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` | -| ⏪️ | `:rewind:` | Revert changes | `⏪️ revert submission handler refactor` | -| 🔀 | `:twisted_rightwards_arrows:` | Merge branches | `🔀 merge feature branch into main` | -| 📄 | `:page_facing_up:` | Add or update license | `📄 add mit license` | -| 🙈 | `:see_no_evil:` | Add or update a .gitignore file | `🙈 add build output to gitignore` | -| 🔊 | `:loud_sound:` | Add or update logs | `🔊 add request logging middleware` | -| 🔇 | `: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` | -| 🧵 | `: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` | -| ✈️ | `:airplane:` | Improve offline support | `✈️ add service worker for offline mode` | -| 🚸 | `:children_crossing:` | Improve user experience / usability | `🚸 simplify onboarding flow` | -| ⚗️ | `:alembic:` | Perform experiments | `⚗️ spike alternative caching strategy` | -| 🚧 | `:construction:` | Work in progress (avoid where possible) | `🚧 wip: partial submission module setup` | - -#### Fallback: Extended Emoji Reference - -When no gitmoji entry fits, consult **[this curated extended reference](https://gist.github.com/marcellodesales/aba1152a91d69f9b39745a08fd73a6f9)** — a multi-source collection covering languages, platforms, cloud infra, and programming strategies that gitmoji doesn't address. - -Key entries from that reference, by category: - -**Bootstrapping & infrastructure** - -| Emoji | Use when | Example | -|-------|----------|---------| -| ⚙️ | App bootstrapping / host setup (distinct from 🔧 config files) | `⚙️ init: 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` | -| 🧮 | Lambda / serverless functions | `🧮 add serverless function trigger` | - -**Containers & deployment** - -| Emoji | Use when | Example | -|-------|----------|---------| -| 🐳 | Docker | `🐳 add dockerfile for api deployment` | - -**Data & storage** - -| Emoji | Use when | Example | -|-------|----------|---------| -| 🛢 | General database (when 🗃️ feels too narrow) | `🛢 add request storage schema` | -| 🐘 | PostgreSQL-specific | `🐘 add postgres connection config` | - -**Documentation** - -| Emoji | Use when | Example | -|-------|----------|---------| -| 📚 | High-level docs, README, wiki (gitmoji's 📝 covers inline/XML docs) | `📚 docs: add api usage documentation` | - -**Observability & runtime** - -| Emoji | Use when | Example | -|-------|----------|---------| -| 🪵 | Structured logging setup | `🪵 add structured logging setup` | -| 📢 | Notifications or event publishing | `📢 add submission event notification` | -| 🏃 | Background workers or hosted services | `🏃 add background worker for processing` | - -**Patterns & architecture** - -| Emoji | Use when | Example | -|-------|----------|---------| -| 🧩 | Components, modules, DI registrations | `🧩 register services in di container` | -| 🏭 | Factory patterns | `🏭 add submission handler factory` | -| 📆 | Schedulers, cron, background jobs | `📆 add cron scheduler for cleanup job` | -| 🤖 | AI / ML integrations | `🤖 add openai client integration` | - -**AI / tools (when relevant)** - -| Emoji | Use when | Example | -|-------|----------|---------| -| 🦾 | AI prompt or agent code | `🦾 add ai prompt template for request triage` | -| 🧠 | LLM integrations | `🧠 integrate chatgpt for request classification` | - -> When in doubt between two options, pick the emoji whose meaning most closely matches *what the change actually does*. If nothing fits, use 🎭 (`:performing_arts:`) as a last resort and note the intent in the message. - ---- +- One logical change per commit — don't bundle unrelated things + +### Prefix and Emoji Reference + +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`. + +--- ## Auto-Approval Mode diff --git a/skills/git-visual-commits/references/commit-language.md b/skills/git-visual-commits/references/commit-language.md new file mode 100644 index 0000000..b5b7afd --- /dev/null +++ b/skills/git-visual-commits/references/commit-language.md @@ -0,0 +1,156 @@ +### 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: + +| Prefix | Use When | +|--------|----------| +| `init:` | Initial setup or configuration of something new | +| `content:` | Endpoint definitions, DTOs, contracts, data shapes | +| `style:` | Code formatting, cleanup, aesthetic changes | +| `fix:` | Bug fixes | +| `refactor:` | Restructuring without behavior change | +| `docs:` | Documentation, XML comments, OpenAPI annotations | + +### 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. + +#### Primary: Gitmoji + +| Emoji | Gitmoji code | Use when | Example | +|-------|-------------|----------|---------| +| 🎉 | `:tada:` | Begin a brand-new project | `🎉 init: 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` | +| ⚡️ | `: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` | +| 🚚 | `: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` | +| 💡 | `: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` | +| 🔨 | `: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` | +| ⬆️ | `:arrow_up:` | Upgrade package dependencies | `⬆️ upgrade dependencies to latest` | +| ⬇️ | `:arrow_down:` | Downgrade dependencies | `⬇️ downgrade ef core to stable release` | +| 📌 | `:pushpin:` | Pin dependencies to specific versions | `📌 pin node version to 20 lts` | +| 🗃️ | `:card_file_box:` | Database changes, ORM models, migrations, entities | `🗃️ add submission entity and db context` | +| 🌱 | `:seedling:` | Add or update seed files | `🌱 add initial request table migration` | +| ✅ | `:white_check_mark:` | Add or update tests | `✅ add integration tests for submission api` | +| 🧪 | `:test_tube:` | Add a failing test (TDD red phase) | `🧪 add failing test for null notes field` | +| 🦺 | `: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` | +| 🔐 | `: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` | +| 👷 | `: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` | +| 🧱 | `: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` | +| ♿️ | `:wheelchair:` | Improve accessibility | `♿️ add aria labels to navigation` | +| 📱 | `:iphone:` | Work on responsive design | `📱 style: 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` | +| ⏪️ | `:rewind:` | Revert changes | `⏪️ revert submission handler refactor` | +| 🔀 | `:twisted_rightwards_arrows:` | Merge branches | `🔀 merge feature branch into main` | +| 📄 | `:page_facing_up:` | Add or update license | `📄 add mit license` | +| 🙈 | `:see_no_evil:` | Add or update a .gitignore file | `🙈 add build output to gitignore` | +| 🔊 | `:loud_sound:` | Add or update logs | `🔊 add request logging middleware` | +| 🔇 | `: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` | +| 🧵 | `: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` | +| ✈️ | `:airplane:` | Improve offline support | `✈️ add service worker for offline mode` | +| 🚸 | `:children_crossing:` | Improve user experience / usability | `🚸 simplify onboarding flow` | +| ⚗️ | `:alembic:` | Perform experiments | `⚗️ spike alternative caching strategy` | +| 🚧 | `:construction:` | Work in progress (avoid where possible) | `🚧 wip: partial submission module setup` | + +#### Fallback: Extended Emoji Reference + +When no gitmoji entry fits, consult **[this curated extended +reference](https://gist.github.com/marcellodesales/aba1152a91d69f9b39745a08fd73a6f9)** +— a multi-source collection covering languages, platforms, cloud infra, +and programming strategies that gitmoji doesn't address. + +Key entries from that reference, by category: + +**Bootstrapping & infrastructure** + +| Emoji | Use when | Example | +|-------|----------|---------| +| ⚙️ | App bootstrapping / host setup (distinct from 🔧 config files) | `⚙️ init: 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` | +| 🧮 | Lambda / serverless functions | `🧮 add serverless function trigger` | + +**Containers & deployment** + +| Emoji | Use when | Example | +|-------|----------|---------| +| 🐳 | Docker | `🐳 add dockerfile for api deployment` | + +**Data & storage** + +| Emoji | Use when | Example | +|-------|----------|---------| +| 🛢 | General database (when 🗃️ feels too narrow) | `🛢 add request storage schema` | +| 🐘 | PostgreSQL-specific | `🐘 add postgres connection config` | + +**Documentation** + +| Emoji | Use when | Example | +|-------|----------|---------| +| 📚 | High-level docs, README, wiki (gitmoji's 📝 covers inline/XML docs) | `📚 docs: add api usage documentation` | + +**Observability & runtime** + +| Emoji | Use when | Example | +|-------|----------|---------| +| 🪵 | Structured logging setup | `🪵 add structured logging setup` | +| 📢 | Notifications or event publishing | `📢 add submission event notification` | +| 🏃 | Background workers or hosted services | `🏃 add background worker for processing` | + +**Patterns & architecture** + +| Emoji | Use when | Example | +|-------|----------|---------| +| 🧩 | Components, modules, DI registrations | `🧩 register services in di container` | +| 🏭 | Factory patterns | `🏭 add submission handler factory` | +| 📆 | Schedulers, cron, background jobs | `📆 add cron scheduler for cleanup job` | +| 🤖 | AI / ML integrations | `🤖 add openai client integration` | + +**AI / tools (when relevant)** + +| Emoji | Use when | Example | +|-------|----------|---------| +| 🦾 | AI prompt or agent code | `🦾 add ai prompt template for request triage` | +| 🧠 | LLM integrations | `🧠 integrate chatgpt for request classification` | + +> When in doubt between two options, pick the emoji whose meaning most +> closely matches *what the change actually does*. If nothing fits, use 🎭 +> (`:performing_arts:`) as a last resort and note the intent in the +> message. From c2484784f34129aeb7ef27c3a85f9d4b597e15ef Mon Sep 17 00:00:00 2001 From: "aicia[bot]" Date: Mon, 16 Mar 2026 22:13:48 +0100 Subject: [PATCH 02/23] =?UTF-8?q?=E2=9C=A8=20add=20git-visual-squash-summa?= =?UTF-8?q?ry=20skill?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Introduce a new squash-summary skill that turns noisy commit stacks into one GitHub-friendly subject line without mutating git state. --- skills/git-visual-squash-summary/SKILL.md | 144 ++++++++++++++++ .../evals/evals.json | 53 ++++++ .../references/commit-language.md | 156 ++++++++++++++++++ 3 files changed, 353 insertions(+) create mode 100644 skills/git-visual-squash-summary/SKILL.md create mode 100644 skills/git-visual-squash-summary/evals/evals.json create mode 100644 skills/git-visual-squash-summary/references/commit-language.md diff --git a/skills/git-visual-squash-summary/SKILL.md b/skills/git-visual-squash-summary/SKILL.md new file mode 100644 index 0000000..9f13953 --- /dev/null +++ b/skills/git-visual-squash-summary/SKILL.md @@ -0,0 +1,144 @@ +--- +name: git-visual-squash-summary +description: > + Turn many commits into one polished squash-ready subject line that + stays compatible with the opinionated wording style of + git-visual-commits. Use this skill whenever the user asks to squash a + branch into one message, write a squash-and-merge summary, summarize a + commit range or PR as one commit, clean up noisy commit history, or asks + for the subject only without actually committing. Treat phrases + like "squash summary", "squash commit message", "summarize this branch", + "turn these commits into one", "rewrite these 10+ commits", or "draft + the squash message" as automatic triggers. This skill is non-mutating: + it inspects git history and diffs, then returns one subject line only. It + detects the dominant theme, preserves technical identifiers where + possible, groups by intent rather than chronology, merges overlapping + commits, uses strong concrete verbs, favors readable GitHub and terminal + output, keeps the subject at or below 72 characters, and does not invent + unsupported changes or drift into changelog wording. +--- + +# Git Visual Squash Summary + +This skill turns a stack of commits into one squash-ready subject line +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 squash-and-merge +subjects and the GitHub squash merge commit field. + +## Non-Negotiable Rules + +- Never stage, commit, amend, rebase, or otherwise mutate git state. +- Read `references/commit-language.md` before choosing any emoji or prefix. +- Detect and center the dominant theme of the commit stack. +- Preserve technical identifiers exactly where possible. +- Group by intent, not chronology. +- Merge repetition and overlapping commits into one clear summary. +- Prefer strong concrete verbs and concise phrasing. +- Favor readable GitHub and terminal output over cleverness. +- Avoid vague filler such as "various improvements". +- Do not treat the result as a changelog entry or bullet-list summary. +- Do not invent unsupported changes. +- Return a subject line only, never a body. +- Keep the subject at or below 72 characters. + +## Workflow + +### Step 1: Resolve the commit set + +Use the most explicit source the user gave you: + +- 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. + +Helpful read-only commands: + +```bash +git status --short --branch +git rev-parse --abbrev-ref HEAD +git rev-parse --abbrev-ref --symbolic-full-name @{upstream} +git merge-base HEAD @{upstream} +git merge-base HEAD main +git merge-base HEAD master +``` + +### Step 2: Inspect the actual changes + +Do not summarize from commit subjects alone when the range is noisy or +long. Inspect both history and net effect so the final message reflects +what actually changed. + +Helpful read-only commands: + +```bash +git log --reverse --oneline +git log --reverse --stat --format=medium +git diff --stat ..HEAD +git diff ..HEAD +``` + +### Step 3: Collapse to semantic intent + +Before drafting the message, reduce the range into the smallest truthful +set of intents: + +- Detect the dominant theme and make it the center of the subject. +- Merge repeated fixups into the final intent they support. +- Prefer the net effect over the path taken to get there. +- Keep documentation-only work separate in your reasoning, but include it + in the final summary only when it materially belongs in the squash. +- Favor the dominant user-facing or maintainer-facing change over internal + churn. + +Ask yourself: "If this history became one reviewed commit, what is the one +sentence explanation of why these changes belong together?" + +### Step 4: Draft the final squash subject + +Use this exact output shape: + +```text + +``` + +Formatting rules: + +- The first line is the squash commit subject. +- The subject must fit within 72 characters. +- Use the shared prefix and emoji guidance in + `references/commit-language.md`. +- Do not add a body, bullets, rationale paragraph, or chronology recap. +- Do not output a changelog fragment, mini-outline, or stacked clauses. +- Favor a clean subject that scans well in GitHub and terminal views. +- Condense to the net effect without dropping important identifiers. + +### Step 5: Return the message only + +Output the finished squash-ready subject line and stop. Do not run +`git commit`, `git bot commit`, `git add`, or any other mutating command. + +## Good Output Characteristics + +- Reads like one polished squash subject, 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`. +- Centers the dominant theme instead of enumerating subtopics. +- Makes the primary change obvious within the first line. +- Fits naturally in the squash merge commit field on GitHub. +- Includes only claims supported by the inspected diff. +- Preserves names such as commands, types, files, APIs, flags, and paths. + +## Bad Output Characteristics + +- Changelog-like wording or release-note phrasing. +- Chronological narration of each commit in order. +- Enumerating multiple subthemes instead of picking the dominant one. +- 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. +- Adding a body or multi-line explanation. +- Exceeding 72 characters in the subject. diff --git a/skills/git-visual-squash-summary/evals/evals.json b/skills/git-visual-squash-summary/evals/evals.json new file mode 100644 index 0000000..d403bf7 --- /dev/null +++ b/skills/git-visual-squash-summary/evals/evals.json @@ -0,0 +1,53 @@ +{ + "skill_name": "git-visual-squash-summary", + "evals": [ + { + "id": 1, + "prompt": "Summarize this branch into one squash commit message. There are 14 commits including fixups, rename follow-ups, and one final docs touch. Give me the message only and do not commit anything.", + "expected_output": "A single squash-ready subject line that reflects the net effect, not a chronological recap, and does not mutate git state.", + "expectations": [ + "Inspects git history and net diff before summarizing", + "Produces one final squash-ready subject line instead of a commit plan", + "Detects and centers the dominant theme of the commit stack", + "Returns a subject only and never adds a body", + "Does not run mutating git commands" + ] + }, + { + "id": 2, + "prompt": "Turn these commits into one polished squash summary for the PR. Preserve identifiers like ValidateSkillTemplates and git-visual-squash-summary exactly where possible.", + "expected_output": "A polished squash subject 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", + "Reads like a curated human-written condensed history rather than a dump of commit subjects", + "Returns a single subject line with no body", + "Avoids inventing unsupported changes" + ] + }, + { + "id": 3, + "prompt": "I only want the squash commit message for this branch versus main. The history is noisy and repetitive, with several tiny follow-up commits. Keep every output line under 72 characters.", + "expected_output": "A concise squash-ready subject with a strict 72-character maximum that collapses repetitive history into intent-based wording.", + "expectations": [ + "Groups by intent rather than chronology", + "Merges repetition and overlapping commits into one summary", + "Favors readable GitHub and terminal output", + "Keeps the subject at or below 72 characters", + "Returns one line only" + ] + }, + { + "id": 4, + "prompt": "Draft a squash-and-merge message for this range, but do not claim anything the diff does not support. Avoid vague filler like various improvements.", + "expected_output": "A truthful squash subject with strong concrete verbs and no unsupported claims or vague filler.", + "expectations": [ + "Uses strong concrete verbs and concise phrasing", + "Avoids vague filler such as various improvements", + "Does not treat the result as a changelog entry", + "Returns only the subject line without a body", + "Does not invent unsupported changes" + ] + } + ] +} diff --git a/skills/git-visual-squash-summary/references/commit-language.md b/skills/git-visual-squash-summary/references/commit-language.md new file mode 100644 index 0000000..b5b7afd --- /dev/null +++ b/skills/git-visual-squash-summary/references/commit-language.md @@ -0,0 +1,156 @@ +### 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: + +| Prefix | Use When | +|--------|----------| +| `init:` | Initial setup or configuration of something new | +| `content:` | Endpoint definitions, DTOs, contracts, data shapes | +| `style:` | Code formatting, cleanup, aesthetic changes | +| `fix:` | Bug fixes | +| `refactor:` | Restructuring without behavior change | +| `docs:` | Documentation, XML comments, OpenAPI annotations | + +### 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. + +#### Primary: Gitmoji + +| Emoji | Gitmoji code | Use when | Example | +|-------|-------------|----------|---------| +| 🎉 | `:tada:` | Begin a brand-new project | `🎉 init: 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` | +| ⚡️ | `: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` | +| 🚚 | `: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` | +| 💡 | `: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` | +| 🔨 | `: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` | +| ⬆️ | `:arrow_up:` | Upgrade package dependencies | `⬆️ upgrade dependencies to latest` | +| ⬇️ | `:arrow_down:` | Downgrade dependencies | `⬇️ downgrade ef core to stable release` | +| 📌 | `:pushpin:` | Pin dependencies to specific versions | `📌 pin node version to 20 lts` | +| 🗃️ | `:card_file_box:` | Database changes, ORM models, migrations, entities | `🗃️ add submission entity and db context` | +| 🌱 | `:seedling:` | Add or update seed files | `🌱 add initial request table migration` | +| ✅ | `:white_check_mark:` | Add or update tests | `✅ add integration tests for submission api` | +| 🧪 | `:test_tube:` | Add a failing test (TDD red phase) | `🧪 add failing test for null notes field` | +| 🦺 | `: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` | +| 🔐 | `: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` | +| 👷 | `: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` | +| 🧱 | `: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` | +| ♿️ | `:wheelchair:` | Improve accessibility | `♿️ add aria labels to navigation` | +| 📱 | `:iphone:` | Work on responsive design | `📱 style: 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` | +| ⏪️ | `:rewind:` | Revert changes | `⏪️ revert submission handler refactor` | +| 🔀 | `:twisted_rightwards_arrows:` | Merge branches | `🔀 merge feature branch into main` | +| 📄 | `:page_facing_up:` | Add or update license | `📄 add mit license` | +| 🙈 | `:see_no_evil:` | Add or update a .gitignore file | `🙈 add build output to gitignore` | +| 🔊 | `:loud_sound:` | Add or update logs | `🔊 add request logging middleware` | +| 🔇 | `: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` | +| 🧵 | `: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` | +| ✈️ | `:airplane:` | Improve offline support | `✈️ add service worker for offline mode` | +| 🚸 | `:children_crossing:` | Improve user experience / usability | `🚸 simplify onboarding flow` | +| ⚗️ | `:alembic:` | Perform experiments | `⚗️ spike alternative caching strategy` | +| 🚧 | `:construction:` | Work in progress (avoid where possible) | `🚧 wip: partial submission module setup` | + +#### Fallback: Extended Emoji Reference + +When no gitmoji entry fits, consult **[this curated extended +reference](https://gist.github.com/marcellodesales/aba1152a91d69f9b39745a08fd73a6f9)** +— a multi-source collection covering languages, platforms, cloud infra, +and programming strategies that gitmoji doesn't address. + +Key entries from that reference, by category: + +**Bootstrapping & infrastructure** + +| Emoji | Use when | Example | +|-------|----------|---------| +| ⚙️ | App bootstrapping / host setup (distinct from 🔧 config files) | `⚙️ init: 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` | +| 🧮 | Lambda / serverless functions | `🧮 add serverless function trigger` | + +**Containers & deployment** + +| Emoji | Use when | Example | +|-------|----------|---------| +| 🐳 | Docker | `🐳 add dockerfile for api deployment` | + +**Data & storage** + +| Emoji | Use when | Example | +|-------|----------|---------| +| 🛢 | General database (when 🗃️ feels too narrow) | `🛢 add request storage schema` | +| 🐘 | PostgreSQL-specific | `🐘 add postgres connection config` | + +**Documentation** + +| Emoji | Use when | Example | +|-------|----------|---------| +| 📚 | High-level docs, README, wiki (gitmoji's 📝 covers inline/XML docs) | `📚 docs: add api usage documentation` | + +**Observability & runtime** + +| Emoji | Use when | Example | +|-------|----------|---------| +| 🪵 | Structured logging setup | `🪵 add structured logging setup` | +| 📢 | Notifications or event publishing | `📢 add submission event notification` | +| 🏃 | Background workers or hosted services | `🏃 add background worker for processing` | + +**Patterns & architecture** + +| Emoji | Use when | Example | +|-------|----------|---------| +| 🧩 | Components, modules, DI registrations | `🧩 register services in di container` | +| 🏭 | Factory patterns | `🏭 add submission handler factory` | +| 📆 | Schedulers, cron, background jobs | `📆 add cron scheduler for cleanup job` | +| 🤖 | AI / ML integrations | `🤖 add openai client integration` | + +**AI / tools (when relevant)** + +| Emoji | Use when | Example | +|-------|----------|---------| +| 🦾 | AI prompt or agent code | `🦾 add ai prompt template for request triage` | +| 🧠 | LLM integrations | `🧠 integrate chatgpt for request classification` | + +> When in doubt between two options, pick the emoji whose meaning most +> closely matches *what the change actually does*. If nothing fits, use 🎭 +> (`:performing_arts:`) as a last resort and note the intent in the +> message. From c9f90c248ba835cfdb8491cbe2ec89ac72dbf7e9 Mon Sep 17 00:00:00 2001 From: "aicia[bot]" Date: Mon, 16 Mar 2026 22:13:53 +0100 Subject: [PATCH 03/23] =?UTF-8?q?=F0=9F=94=A8=20add=20git=20visual=20skill?= =?UTF-8?q?=20sync=20validation?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Extend the repo validator so the shared commit-language references stay in sync and the new squash-summary skill contract is enforced. --- scripts/validate-skill-templates.ps1 | 45 ++++++++++++++++++++++++++++ 1 file changed, 45 insertions(+) diff --git a/scripts/validate-skill-templates.ps1 b/scripts/validate-skill-templates.ps1 index 753b5c2..2e60240 100644 --- a/scripts/validate-skill-templates.ps1 +++ b/scripts/validate-skill-templates.ps1 @@ -604,6 +604,7 @@ Add-ValidationResult -Results $results -Name 'Strong-name skill matches FORMS su Add-ValidationResult -Results $results -Name 'Git visual commits skill enforces identity lock and umbrella commit rejection' -Action { $skill = Get-FileText -RepoRoot $repoRoot -RelativePath 'skills/git-visual-commits/SKILL.md' -GitRef $Ref $evals = Get-FileText -RepoRoot $repoRoot -RelativePath 'skills/git-visual-commits/evals/evals.json' -GitRef $Ref + $commitLanguage = Get-FileText -RepoRoot $repoRoot -RelativePath 'skills/git-visual-commits/references/commit-language.md' -GitRef $Ref Assert-Contains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle 'automatic trigger for this skill, not as a casual hint.' Assert-Contains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle '### Identity Lock' @@ -617,10 +618,16 @@ Add-ValidationResult -Results $results -Name 'Git visual commits skill enforces Assert-Contains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle 'Do **not** hard-wrap commit bodies at 72 characters; keep short bodies as normal prose' 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-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 — Gitmoji First, Fallback Second' Assert-Contains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle 'Even in auto-approval mode, surface the commit buckets explicitly before committing.' Assert-Contains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle 'Do not pass literal `\n` escape sequences and assume the shell will rewrite them.' Assert-Contains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle 'Prefer grammatical sentence and paragraph breaks over column-based hard wrapping.' Assert-Contains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle 'Then always run `git log -1 --format="%an <%ae>"` and verify that the author matches the requested identity mode before reporting success.' + Assert-Contains -Name 'git-visual-commits/references/commit-language.md' -Content $commitLanguage -Needle '### Allowed Prefixes' + Assert-Contains -Name 'git-visual-commits/references/commit-language.md' -Content $commitLanguage -Needle '### Emoji Selection — 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/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' @@ -629,6 +636,44 @@ 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' } +Add-ValidationResult -Results $results -Name 'Git visual squash summary skill stays self-contained and shares commit language rules' -Action { + $skill = Get-FileText -RepoRoot $repoRoot -RelativePath 'skills/git-visual-squash-summary/SKILL.md' -GitRef $Ref + $evals = Get-FileText -RepoRoot $repoRoot -RelativePath 'skills/git-visual-squash-summary/evals/evals.json' -GitRef $Ref + $commitLanguage = Get-FileText -RepoRoot $repoRoot -RelativePath 'skills/git-visual-squash-summary/references/commit-language.md' -GitRef $Ref + $commitLanguageCommits = Get-FileText -RepoRoot $repoRoot -RelativePath 'skills/git-visual-commits/references/commit-language.md' -GitRef $Ref + + if ($commitLanguage -cne $commitLanguageCommits) { + throw 'git-visual commit-language references must stay byte-for-byte identical' + } + + Assert-Contains -Name 'git-visual-squash-summary/SKILL.md' -Content $skill -Needle 'This skill turns a stack of commits into one squash-ready subject line' + 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 'detects the dominant theme' + 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 '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 bullet-list summary.' + Assert-Contains -Name 'git-visual-squash-summary/SKILL.md' -Content $skill -Needle 'Return a subject line only, never a body.' + Assert-Contains -Name 'git-visual-squash-summary/SKILL.md' -Content $skill -Needle 'Keep the subject 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 'Fits naturally in the squash merge commit field on GitHub.' + Assert-Contains -Name 'git-visual-squash-summary/SKILL.md' -Content $skill -Needle 'Changelog-like wording or release-note phrasing.' + Assert-Contains -Name 'git-visual-squash-summary/SKILL.md' -Content $skill -Needle 'Output the finished squash-ready subject line and stop.' + Assert-Contains -Name 'git-visual-squash-summary/SKILL.md' -Content $skill -Needle '`git bot commit`, `git add`, or any other mutating command.' + Assert-NotContains -Name 'git-visual-squash-summary/SKILL.md' -Content $skill -Needle '' + Assert-NotContains -Name 'git-visual-squash-summary/SKILL.md' -Content $skill -Needle 'The body is usually 1-4 wrapped lines' + Assert-Contains -Name 'git-visual-squash-summary/references/commit-language.md' -Content $commitLanguage -Needle '### Allowed Prefixes' + Assert-Contains -Name 'git-visual-squash-summary/references/commit-language.md' -Content $commitLanguage -Needle '### Emoji Selection — Gitmoji First, Fallback Second' + + Assert-Contains -Name 'git-visual-squash-summary/evals/evals.json' -Content $evals -Needle 'Does not run mutating git commands' + Assert-Contains -Name 'git-visual-squash-summary/evals/evals.json' -Content $evals -Needle 'Detects and centers the dominant theme of the commit stack' + Assert-Contains -Name 'git-visual-squash-summary/evals/evals.json' -Content $evals -Needle 'Reads like a curated human-written condensed history rather than a dump of commit subjects' + Assert-Contains -Name 'git-visual-squash-summary/evals/evals.json' -Content $evals -Needle 'Favors readable GitHub and terminal output' + Assert-Contains -Name 'git-visual-squash-summary/evals/evals.json' -Content $evals -Needle 'Returns a subject only and never adds a body' + Assert-Contains -Name 'git-visual-squash-summary/evals/evals.json' -Content $evals -Needle 'Keeps the subject at or below 72 characters' + Assert-Contains -Name 'git-visual-squash-summary/evals/evals.json' -Content $evals -Needle 'Does not treat the result as a changelog entry' + Assert-Contains -Name 'git-visual-squash-summary/evals/evals.json' -Content $evals -Needle 'Does not invent unsupported changes' +} + Add-ValidationResult -Results $results -Name 'Rendered app worker template leaves no unexpected placeholders' -Action { $files = @( 'skills/dotnet-new-app-slnx/assets/shared/Directory.Packages.props', From 86fa3da2ba77bb410581f5a884eecbaa62f75d8e Mon Sep 17 00:00:00 2001 From: "aicia[bot]" Date: Mon, 16 Mar 2026 22:14:00 +0100 Subject: [PATCH 04/23] =?UTF-8?q?=F0=9F=93=9A=20docs:=20add=20squash=20sum?= =?UTF-8?q?mary=20docs=20and=20changelog?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Document the new squash-summary skill in the README and capture the v0.1.0 and v0.2.0 release history in a Keep a Changelog-formatted changelog. --- CHANGELOG.md | 68 ++++++++++++++++++++++++++++++++++++++++++++++++++++ README.md | 42 ++++++++++++++++++++++++++------ 2 files changed, 103 insertions(+), 7 deletions(-) create mode 100644 CHANGELOG.md diff --git a/CHANGELOG.md b/CHANGELOG.md new file mode 100644 index 0000000..aa1ecb8 --- /dev/null +++ b/CHANGELOG.md @@ -0,0 +1,68 @@ +# Changelog + +All notable changes to this project will be documented in this file. + +The format is based on [Keep a Changelog](https://keepachangelog.com/en/1.1.0/), +and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0.html). + +## [Unreleased] + +## [0.2.0] - 2026-03-16 + +### Added + +- Added per-skill `evals/evals.json` coverage across the repo, including + deterministic validation for scaffold behavior and skill contracts. +- Expanded `dotnet-new-app-slnx` with explicit web-family variants for + Empty Web, Web API, MVC, and Web App / Razor scaffolds. +- Introduced a NuGet-backed app package resolver so generated + `Directory.Packages.props` files use current compatible versions. + +### Changed + +- Hardened the .NET app and library scaffold skills around required + outputs, current-folder generation, supported TFM choices, and clearer + usage guidance. +- Tightened repo documentation and local skill-sync guidance so README, + policy, and install expectations stay aligned. +- Strengthened `git-visual-commits` with identity lock, `yolo` guardrails, + post-commit verification, and clearer umbrella-commit rejection rules. + +### Fixed + +- Improved scaffold fidelity so generated assets stay complete, shared + files remain synchronized, and emitted app templates are validation- and + compile-ready. + +## [0.1.0] - 2026-03-15 + +### Added + +- Launched the initial skill suite with `git-visual-commits`, + `trunk-first-repo`, `dotnet-strong-name-signing`, + `dotnet-new-lib-slnx`, and `dotnet-new-app-slnx`. +- Added repo governance and contributor guidance, including the initial + `README`, `CONTRIBUTING`, `AGENTS.md`, license, and ignore rules. +- Added shared scaffold assets for CI, packaging, documentation, + benchmarking, and TFM-aware test environments for the .NET skills. + +### Changed + +- Split the original combined .NET scaffolder into dedicated app and + library skills with clearer scope boundaries and lower-friction prompts. +- Refined scaffold defaults to derive more metadata from repo state, + official .NET support data, and current package feeds instead of stale + hardcoded values. +- Evolved `git-visual-commits` from a basic commit helper into an + opinionated workflow with reviewable commit plans, collaborative + attribution modes, richer gitmoji coverage, and body-by-default support. + +### Fixed + +- 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.2.0...HEAD +[0.2.0]: https://github.com/codebeltnet/agentic/compare/v0.1.0...v0.2.0 +[0.1.0]: https://github.com/codebeltnet/agentic/compare/7eaf364...v0.1.0 diff --git a/README.md b/README.md index 7991776..4da41e5 100644 --- a/README.md +++ b/README.md @@ -42,6 +42,7 @@ If you want a bundle of skills always available, just install them all: ```bash npx skills add https://github.com/codebeltnet/agentic --skill git-visual-commits +npx skills add https://github.com/codebeltnet/agentic --skill git-visual-squash-summary npx skills add https://github.com/codebeltnet/agentic --skill trunk-first-repo npx skills add https://github.com/codebeltnet/agentic --skill dotnet-strong-name-signing # npx skills add https://github.com/codebeltnet/agentic --skill another-skill @@ -60,10 +61,11 @@ npx skills add https://github.com/codebeltnet/agentic --skill dotnet-strong-name ## Available Skills -| 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. | -| [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. | +| 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-visual-squash-summary](skills/git-visual-squash-summary/SKILL.md) | Non-mutating squash-subject companion to `git-visual-commits`. Turns noisy commit stacks into one polished squash-ready subject line for the GitHub squash merge field, detecting the dominant theme, preserving technical identifiers, favoring readable GitHub/terminal output, and avoiding changelog-style wording or unsupported claims. | +| [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. | | [dotnet-new-app-slnx](skills/dotnet-new-app-slnx/SKILL.md) | Scaffold a new .NET standalone application solution following codebeltnet engineering conventions. Supports Console, Web, and Worker host families with Startup or Minimal hosting patterns; Web expands into Empty Web, Web API, MVC, or Web App / Razor, plus functional tests and a simplified CI pipeline. | | [trunk-first-repo](skills/trunk-first-repo/SKILL.md) | Initialize a git repository following [scaled trunk-based development](https://trunkbaseddevelopment.com/#scaled-trunk-based-development). Seeds an empty `main` branch and creates a versioned feature branch (`v0.1.0/init`), enforcing a PR-first workflow where content only reaches main through peer-reviewed pull requests. | | [dotnet-strong-name-signing](skills/dotnet-strong-name-signing/SKILL.md) | 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. Defaults to 1024-bit RSA (matching `sn.exe`), with 2048 and 4096 available as options. | @@ -78,6 +80,12 @@ If your Markdown viewer supports code-block copy buttons, each command below sho npx skills add https://github.com/codebeltnet/agentic --skill git-visual-commits ``` +`git-visual-squash-summary` + +```bash +npx skills add https://github.com/codebeltnet/agentic --skill git-visual-squash-summary +``` + `dotnet-new-lib-slnx` ```bash @@ -120,9 +128,29 @@ Commit messages are the most-read documentation in any codebase — yet they're - **Semantic intent splitting** — groups commits by rationale, not just file type — config and test logic are always separate - **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 - -### Why dotnet-new-lib-slnx and dotnet-new-app-slnx? +- **Squash-and-merge friendly** — structured commits make PR squash summaries read like a changelog + +### Why git-visual-squash-summary? + +Sometimes the history is already written and the only thing you need is +the final squash subject. A long branch with fixups, rename follow-ups, +review nits, and repeated attempts often has a clean net effect but a +messy chronological story. That is where **git-visual-squash-summary** +fits: it reads the real history and diff, then compresses them into one +truthful squash-ready subject line. + +- **Same visual language** — reuses the same prefix and emoji rules as `git-visual-commits` +- **Subject-only by design** — returns the subject line only, never a body +- **Non-mutating by design** — drafts the wording only and does not touch git state +- **Dominant-theme first** — picks the main story instead of listing every sub-change +- **Intent over chronology** — collapses noisy commit stacks into the net effect +- **Identifier-safe wording** — preserves technical names, paths, flags, and types where possible +- **Readable in GitHub and terminals** — optimized for the squash merge field and compact commit views +- **Strict 72-char subject** — ready for teams that want compact squash summaries +- **Not a changelog** — avoids release-note phrasing and commit-subject dumps +- **No unsupported claims** — summarizes only what the inspected diff can justify + +### Why dotnet-new-lib-slnx and dotnet-new-app-slnx? Starting a new .NET solution "from scratch" usually means copying from your last project, deleting half of it, and spending an hour wiring up CI, MSBuild props, versioning, and code quality tooling. Every new repo drifts slightly from the last one. Six months later, no two solutions look the same. From 5f5324bd392228ef341f232b8f6fd1badb5d64b0 Mon Sep 17 00:00:00 2001 From: "aicia[bot]" Date: Mon, 16 Mar 2026 22:27:00 +0100 Subject: [PATCH 05/23] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20refactor:=20tighten?= =?UTF-8?q?=20git=20visual=20skill=20grouping=20rules?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Clarify that new repo capabilities, existing-skill refactors, and shared reference sync guidance are separate intents. Add eval coverage so mixed capability and refactor diffs do not collapse into one commit. --- skills/git-visual-commits/SKILL.md | 33 +++++++++++++++------- skills/git-visual-commits/evals/evals.json | 11 ++++++++ skills/git-visual-squash-summary/SKILL.md | 3 ++ 3 files changed, 37 insertions(+), 10 deletions(-) diff --git a/skills/git-visual-commits/SKILL.md b/skills/git-visual-commits/SKILL.md index e517225..dca4d72 100644 --- a/skills/git-visual-commits/SKILL.md +++ b/skills/git-visual-commits/SKILL.md @@ -158,6 +158,9 @@ 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. --- @@ -220,11 +223,13 @@ Run `git status` and `git diff` (and `git diff --staged` if there are staged cha 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. -Derive categories from the actual diff — don't assume a fixed set. Common categories include: - -- **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 +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 +- **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 - **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 @@ -232,7 +237,9 @@ Derive categories from the actual diff — don't assume a fixed set. Common cate - **Application code** — new features, bug fixes, refactors, business logic - **Test logic** — changed assertions, updated expectations, new test cases, modified test behavior -**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. +**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. This classification drives grouping in Step 3. Files with different semantic intents almost never belong in the same commit. @@ -260,10 +267,12 @@ 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: -- Config/setup files together (app host, bootstrapping) -- Environment and infrastructure config together (test runners, CI matrix, container settings) -- New feature or module code together +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) @@ -285,12 +294,16 @@ Documentation files (`CHANGELOG.md`, `AGENTS.md`, `README.md`, `CONTRIBUTING.md` When a repo like this one mixes skill changes, scaffold assets, validators, and repo docs, split them by intent: +- **New repo-managed skill** — a newly introduced `skills//` folder and its local `evals/` or `references/` +- **Existing skill refactor** — extracting shared rules, renaming sections, or reorganizing an existing skill - **Skill contract files** — `SKILL.md`, `FORMS.md`, `references/`, `evals/` - **Template/runtime files** — `assets/`, scaffold helper scripts - **Validation/tooling** — validator scripts, repo checks - **Repo docs/rules** — `README.md`, `AGENTS.md`, `CONTRIBUTING.md` Do not merge these into one commit unless the diff is truly single-purpose and the explanation still fits one sentence without using "and". + +If a commit both introduces a brand-new skill and refactors an existing skill to support it, prefer separate commits. "Related" is not enough — the repo history should make it obvious which commit added the capability and which commit reorganized existing behavior around it. #### Rename vs removal distinction diff --git a/skills/git-visual-commits/evals/evals.json b/skills/git-visual-commits/evals/evals.json index e30509b..79e6edb 100644 --- a/skills/git-visual-commits/evals/evals.json +++ b/skills/git-visual-commits/evals/evals.json @@ -68,6 +68,17 @@ "Stops with a clear blocker when alias.bot is unavailable", "Does not fall back to git commit when git bot commit was explicitly requested" ] + }, + { + "id": 7, + "prompt": "Do a git bot commit, yolo. The diff introduces a brand-new skill folder, extracts shared wording out of an existing skill, updates the validator, and refreshes README docs.", + "expected_output": "An auto-approved bot commit plan that separates the new repo capability from the existing-skill refactor, validator coverage, and repo docs.", + "expectations": [ + "Treats a newly introduced skill folder as a separate repo capability intent", + "Separates new skill introduction from existing skill refactor work", + "Separates validator changes from skill contract changes when the rationale differs", + "Keeps README or changelog updates in their own documentation-focused commit" + ] } ] } diff --git a/skills/git-visual-squash-summary/SKILL.md b/skills/git-visual-squash-summary/SKILL.md index 9f13953..c0c8fff 100644 --- a/skills/git-visual-squash-summary/SKILL.md +++ b/skills/git-visual-squash-summary/SKILL.md @@ -30,6 +30,9 @@ subjects and the GitHub squash merge commit field. - Never stage, commit, amend, rebase, or otherwise mutate git state. - Read `references/commit-language.md` before choosing any emoji or 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. - Detect and center the dominant theme of the commit stack. - Preserve technical identifiers exactly where possible. - Group by intent, not chronology. From d5d34d0c78d115d79fd35ed12b8713bb0fc0703e Mon Sep 17 00:00:00 2001 From: "aicia[bot]" Date: Mon, 16 Mar 2026 22:27:09 +0100 Subject: [PATCH 06/23] =?UTF-8?q?=F0=9F=94=A8=20add=20ci-backed=20skill=20?= =?UTF-8?q?template=20validation?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Run the existing validator on every push and pull request, and harden UTF-8 handling so the same checks behave consistently in Windows PowerShell and CI. --- .../workflows/validate-skill-templates.yml | 17 +++++++++++++ scripts/validate-skill-templates.ps1 | 25 ++++++++++++++++--- 2 files changed, 38 insertions(+), 4 deletions(-) create mode 100644 .github/workflows/validate-skill-templates.yml diff --git a/.github/workflows/validate-skill-templates.yml b/.github/workflows/validate-skill-templates.yml new file mode 100644 index 0000000..dd0df8a --- /dev/null +++ b/.github/workflows/validate-skill-templates.yml @@ -0,0 +1,17 @@ +name: Validate Skill Templates + +on: + pull_request: + push: + +jobs: + validate-skill-templates: + runs-on: ubuntu-latest + + steps: + - name: Checkout + uses: actions/checkout@v4 + + - name: Run validator + shell: pwsh + run: pwsh -NoProfile -File ./scripts/validate-skill-templates.ps1 diff --git a/scripts/validate-skill-templates.ps1 b/scripts/validate-skill-templates.ps1 index 2e60240..e5b0d39 100644 --- a/scripts/validate-skill-templates.ps1 +++ b/scripts/validate-skill-templates.ps1 @@ -6,6 +6,11 @@ $ErrorActionPreference = 'Stop' Set-StrictMode -Version Latest +$utf8NoBom = [System.Text.UTF8Encoding]::new($false) +[Console]::InputEncoding = $utf8NoBom +[Console]::OutputEncoding = $utf8NoBom +$OutputEncoding = $utf8NoBom + function Get-RepoRoot { return (Resolve-Path (Join-Path $PSScriptRoot '..')).Path } @@ -66,7 +71,7 @@ function Get-FileText { if (-not (Test-Path $fullPath)) { throw "Missing file: $RelativePath" } - return [System.IO.File]::ReadAllText($fullPath) + return [System.IO.File]::ReadAllText($fullPath, $utf8NoBom) } $showTarget = '{0}:{1}' -f $GitRef, ($RelativePath -replace '\\', '/') @@ -620,13 +625,22 @@ Add-ValidationResult -Results $results -Name 'Git visual commits skill enforces 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-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 — Gitmoji First, Fallback Second' + 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.' Assert-Contains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle 'Do not pass literal `\n` escape sequences and assume the shell will rewrite them.' Assert-Contains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle 'Prefer grammatical sentence and paragraph breaks over column-based hard wrapping.' Assert-Contains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle 'Then always run `git log -1 --format="%an <%ae>"` and verify that the author matches the requested identity mode before reporting success.' + Assert-Contains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle '**New repo capabilities**' + 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 '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/`' + Assert-Contains -Name 'git-visual-commits/SKILL.md' -Content $skill -Needle 'If a commit both introduces a brand-new skill and refactors an existing skill to support it, prefer separate commits.' Assert-Contains -Name 'git-visual-commits/references/commit-language.md' -Content $commitLanguage -Needle '### Allowed Prefixes' - Assert-Contains -Name 'git-visual-commits/references/commit-language.md' -Content $commitLanguage -Needle '### Emoji Selection — Gitmoji First, Fallback Second' + 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/evals/evals.json' -Content $evals -Needle 'Does not let yolo collapse multiple semantic intents into one umbrella commit' @@ -634,6 +648,8 @@ Add-ValidationResult -Results $results -Name 'Git visual commits skill enforces Assert-Contains -Name 'git-visual-commits/evals/evals.json' -Content $evals -Needle 'Verifies the stored commit body does not contain literal \\n escape sequences' Assert-Contains -Name 'git-visual-commits/evals/evals.json' -Content $evals -Needle 'Does not hard-wrap a short commit body mid-sentence just to satisfy a column limit' 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' } Add-ValidationResult -Results $results -Name 'Git visual squash summary skill stays self-contained and shares commit language rules' -Action { @@ -662,7 +678,8 @@ Add-ValidationResult -Results $results -Name 'Git visual squash summary skill st Assert-NotContains -Name 'git-visual-squash-summary/SKILL.md' -Content $skill -Needle '' Assert-NotContains -Name 'git-visual-squash-summary/SKILL.md' -Content $skill -Needle 'The body is usually 1-4 wrapped lines' Assert-Contains -Name 'git-visual-squash-summary/references/commit-language.md' -Content $commitLanguage -Needle '### Allowed Prefixes' - Assert-Contains -Name 'git-visual-squash-summary/references/commit-language.md' -Content $commitLanguage -Needle '### Emoji Selection — Gitmoji First, Fallback Second' + Assert-Contains -Name 'git-visual-squash-summary/references/commit-language.md' -Content $commitLanguage -Needle '### Emoji Selection' + Assert-Contains -Name 'git-visual-squash-summary/references/commit-language.md' -Content $commitLanguage -Needle 'Gitmoji First, Fallback Second' Assert-Contains -Name 'git-visual-squash-summary/evals/evals.json' -Content $evals -Needle 'Does not run mutating git commands' Assert-Contains -Name 'git-visual-squash-summary/evals/evals.json' -Content $evals -Needle 'Detects and centers the dominant theme of the commit stack' From 6b93453dab1128f3ef37b3f16b678d81c0fa1c73 Mon Sep 17 00:00:00 2001 From: "aicia[bot]" Date: Mon, 16 Mar 2026 22:27:16 +0100 Subject: [PATCH 07/23] =?UTF-8?q?=F0=9F=93=9D=20docs:=20document=20local-f?= =?UTF-8?q?irst=20skill=20validation?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Explain that contributors should run validate-skill-templates.ps1 locally for fast feedback while GitHub Actions reruns the same checks as the merge safety net. --- CONTRIBUTING.md | 5 +++++ README.md | 7 +++++++ 2 files changed, 12 insertions(+) diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index 8e7ec68..fc03995 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -106,6 +106,10 @@ Use the repo validation harness before submitting scaffold or template changes: powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\validate-skill-templates.ps1 ``` +Run the validator locally first for the fastest feedback loop. GitHub +Actions also runs the same script on pushes and pull requests, but CI is +the backstop, not the primary authoring loop. + To compare a change against the initial imported version, run the same harness against a git ref: ```powershell @@ -120,6 +124,7 @@ powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\validate-skill-tem - [ ] At least one eval in `evals/evals.json` - [ ] The skill's `evals/evals.json` exists and its `skill_name` matches the folder/frontmatter name - [ ] `scripts/validate-skill-templates.ps1` passes for the current working tree when changing scaffold or template behavior +- [ ] If CI is enabled for the branch, the GitHub Actions validation job passes too - [ ] Skill evals are intended to run from `$env:TEMP/-workspace/`, not from inside the repo - [ ] Changed skill files are synced across `skills//`, `~/.claude/skills//`, and `~/.agents/skills//` - [ ] Skill added to the table in `README.md` diff --git a/README.md b/README.md index 4da41e5..d32473c 100644 --- a/README.md +++ b/README.md @@ -13,6 +13,11 @@ Another repo rule is intentionally strict: every repo-managed skill ships with i There is also an interim Codex compatibility workaround in [AGENTS.md](AGENTS.md): the repo mirrors the current `~/.codex/AGENTS.override.md` decision and code-change rules so they still apply even when a Codex build fails to auto-load that personal override file. 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. + +Validation follows the same philosophy: run +`scripts/validate-skill-templates.ps1` locally for the fast feedback +loop, and let GitHub Actions rerun that same script on pushes and pull +requests as the safety net. ## Install a skill @@ -125,6 +130,8 @@ Commit messages are the most-read documentation in any codebase — yet they're - **Commit body by default** — every commit explains *why*, not just *what* — opt out with "tmi" or "no-body" - **Commit bodies are verified after write** — the workflow now checks the stored commit body so literal escape sequences like `\n` do not leak into history - **Short bodies stay readable** — the workflow no longer hard-wraps short commit bodies at 72 characters and instead prefers normal prose with sentence-level judgment +- **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 - **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 From a518b838fea9b1c16e3c3132bf76f675c03aee74 Mon Sep 17 00:00:00 2001 From: "aicia[bot]" Date: Mon, 16 Mar 2026 22:52:54 +0100 Subject: [PATCH 08/23] =?UTF-8?q?=E2=9C=A8=20add=20grouped=20git=20visual?= =?UTF-8?q?=20squash=20summaries?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace the subject-only squash contract with grouped summary lines that preserve distinct high-signal efforts, merge overlap, and drop low-signal noise. --- skills/git-visual-squash-summary/SKILL.md | 109 ++++++++++-------- .../evals/evals.json | 45 +++++--- 2 files changed, 91 insertions(+), 63 deletions(-) diff --git a/skills/git-visual-squash-summary/SKILL.md b/skills/git-visual-squash-summary/SKILL.md index c0c8fff..b165fde 100644 --- a/skills/git-visual-squash-summary/SKILL.md +++ b/skills/git-visual-squash-summary/SKILL.md @@ -1,30 +1,35 @@ --- name: git-visual-squash-summary description: > - Turn many commits into one polished squash-ready subject line that + Turn many commits into a curated grouped squash summary that stays compatible with the opinionated wording style of git-visual-commits. Use this skill whenever the user asks to squash a - branch into one message, write a squash-and-merge summary, summarize a - commit range or PR as one commit, clean up noisy commit history, or asks - for the subject only without actually committing. Treat phrases + 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 actually committing. + Treat phrases like "squash summary", "squash commit message", "summarize this branch", - "turn these commits into one", "rewrite these 10+ commits", or "draft - the squash message" as automatic triggers. This skill is non-mutating: - it inspects git history and diffs, then returns one subject line only. It - detects the dominant theme, preserves technical identifiers where - possible, groups by intent rather than chronology, merges overlapping - commits, uses strong concrete verbs, favors readable GitHub and terminal - output, keeps the subject at or below 72 characters, and does not invent - unsupported changes or drift into changelog wording. + "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. --- # Git Visual Squash Summary -This skill turns a stack of commits into one squash-ready subject line +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 squash-and-merge -subjects and the GitHub squash merge commit field. +prefix language, 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. ## Non-Negotiable Rules @@ -33,17 +38,19 @@ subjects and the GitHub squash merge commit field. - Keep `references/commit-language.md` byte-for-byte aligned with the `git-visual-commits` copy; the validator and CI both enforce that sync contract. -- Detect and center the dominant theme of the commit stack. - Preserve technical identifiers exactly where possible. - Group by intent, not chronology. -- Merge repetition and overlapping commits into one clear summary. +- Retain only distinct high-signal change groups. +- Merge repetition and overlapping commits into their parent group. +- Drop low-signal noise such as typo-only, fixup-only, and trivial follow-up + commits unless they materially change a retained group. - Prefer strong concrete verbs and concise phrasing. - Favor readable GitHub and terminal output over cleverness. - Avoid vague filler such as "various improvements". -- Do not treat the result as a changelog entry or bullet-list summary. +- Do not treat the result as a changelog entry or a dump of commit subjects. - Do not invent unsupported changes. -- Return a subject line only, never a body. -- Keep the subject at or below 72 characters. +- Return grouped lines only, never a title or body. +- Keep every output line at or below 72 characters. ## Workflow @@ -86,62 +93,72 @@ git diff ..HEAD ### Step 3: Collapse to semantic intent -Before drafting the message, reduce the range into the smallest truthful -set of intents: +Before drafting the summary, reduce the range into the smallest truthful +set of retained groups: -- Detect the dominant theme and make it the center of the subject. -- Merge repeated fixups into the final intent they support. +- Collapse repeated fixups into the group they support. +- 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. - Keep documentation-only work separate in your reasoning, but include it - in the final summary only when it materially belongs in the squash. -- Favor the dominant user-facing or maintainer-facing change over internal - churn. + only when it represents a meaningful unique change. +- Highlight distinct meaningful efforts instead of forcing one dominant + umbrella theme. -Ask yourself: "If this history became one reviewed commit, what is the one -sentence explanation of why these changes belong together?" +Ask yourself: "If I had to explain the real work in 2-5 compact lines, +what are the distinct changes that mattered?" -### Step 4: Draft the final squash subject +### Step 4: Draft the grouped summary Use this exact output shape: ```text - + + + ``` Formatting rules: -- The first line is the squash commit subject. -- The subject must fit within 72 characters. +- 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. - Use the shared prefix and emoji guidance in `references/commit-language.md`. -- Do not add a body, bullets, rationale paragraph, or chronology recap. -- Do not output a changelog fragment, mini-outline, or stacked clauses. -- Favor a clean subject that scans well in GitHub and terminal views. -- Condense to the net effect without dropping important identifiers. +- 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. +- Condense to the real grouped effort without dropping important + identifiers. -### Step 5: Return the message only +### Step 5: Return the grouped lines only -Output the finished squash-ready subject line and stop. Do not run +Output the finished grouped summary lines and stop. Do not run `git commit`, `git bot commit`, `git add`, or any other mutating command. ## Good Output Characteristics -- Reads like one polished squash subject, not a stitched list of commits. +- 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`. -- Centers the dominant theme instead of enumerating subtopics. -- Makes the primary change obvious within the first line. -- Fits naturally in the squash merge commit field on GitHub. +- 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. ## Bad Output Characteristics - Changelog-like wording or release-note phrasing. - Chronological narration of each commit in order. -- Enumerating multiple subthemes instead of picking the dominant one. +- Dumping raw commit subjects line by line. +- Collapsing several unique top-level efforts into one stitched sentence. - 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. -- Adding a body or multi-line explanation. -- Exceeding 72 characters in the subject. +- Adding a title, body, bullets, or numbered outline. +- Exceeding 72 characters on any output line. diff --git a/skills/git-visual-squash-summary/evals/evals.json b/skills/git-visual-squash-summary/evals/evals.json index d403bf7..ce35065 100644 --- a/skills/git-visual-squash-summary/evals/evals.json +++ b/skills/git-visual-squash-summary/evals/evals.json @@ -3,51 +3,62 @@ "evals": [ { "id": 1, - "prompt": "Summarize this branch into one squash commit message. There are 14 commits including fixups, rename follow-ups, and one final docs touch. Give me the message only and do not commit anything.", - "expected_output": "A single squash-ready subject line that reflects the net effect, not a chronological recap, and does not mutate git state.", + "prompt": "Summarize this branch into a grouped squash summary. There are 14 commits including fixups, rename follow-ups, and one final docs touch. Give me the summary lines only and do not commit anything.", + "expected_output": "A grouped squash summary that reflects the distinct retained work, not a chronological recap, and does not mutate git state.", "expectations": [ "Inspects git history and net diff before summarizing", - "Produces one final squash-ready subject line instead of a commit plan", - "Detects and centers the dominant theme of the commit stack", - "Returns a subject only and never adds a body", + "Produces grouped summary lines instead of a commit plan", + "Returns grouped lines only and never adds a title or body", + "Merges repetition and overlapping commits into retained groups", "Does not run mutating git commands" ] }, { "id": 2, - "prompt": "Turn these commits into one polished squash summary for the PR. Preserve identifiers like ValidateSkillTemplates and git-visual-squash-summary exactly where possible.", - "expected_output": "A polished squash subject that keeps important technical identifiers intact and uses the shared git-visual wording style.", + "prompt": "Turn these commits into a polished grouped squash summary for the PR. Preserve identifiers like ValidateSkillTemplates and git-visual-squash-summary exactly where possible.", + "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", "Reads like a curated human-written condensed history rather than a dump of commit subjects", - "Returns a single subject line with no body", + "Keeps distinct meaningful efforts on separate lines", "Avoids inventing unsupported changes" ] }, { "id": 3, - "prompt": "I only want the squash commit message for this branch versus main. The history is noisy and repetitive, with several tiny follow-up commits. Keep every output line under 72 characters.", - "expected_output": "A concise squash-ready subject with a strict 72-character maximum that collapses repetitive history into intent-based wording.", + "prompt": "I only want the grouped squash summary for this branch versus main. The history is noisy and repetitive, with several tiny follow-up commits and typo fixes. Keep every output line under 72 characters.", + "expected_output": "A concise grouped summary with a strict 72-character maximum per line that collapses repetitive history into intent-based wording and drops low-signal noise.", "expectations": [ "Groups by intent rather than chronology", - "Merges repetition and overlapping commits into one summary", + "Drops low-signal noise such as typo-only or trivial follow-up commits", "Favors readable GitHub and terminal output", - "Keeps the subject at or below 72 characters", - "Returns one line only" + "Keeps every output line at or below 72 characters", + "Does not prepend a title, bullets, or numbering" ] }, { "id": 4, - "prompt": "Draft a squash-and-merge message for this range, but do not claim anything the diff does not support. Avoid vague filler like various improvements.", - "expected_output": "A truthful squash subject with strong concrete verbs and no unsupported claims or vague filler.", + "prompt": "Draft a grouped squash-and-merge summary for this range, but do not claim anything the diff does not support. Avoid vague filler like various improvements.", + "expected_output": "A truthful grouped summary with strong concrete verbs and no unsupported claims or vague filler.", "expectations": [ "Uses strong concrete verbs and concise phrasing", "Avoids vague filler such as various improvements", - "Does not treat the result as a changelog entry", - "Returns only the subject line without a body", + "Does not treat the result as a changelog entry or commit-subject dump", + "Returns grouped lines only without a title or body", "Does not invent unsupported changes" ] + }, + { + "id": 5, + "prompt": "We have about 100 commits here: 30 overlap heavily, 20 are typo-level noise, and the remaining work collapses into five real categories. Give me the curated grouped summary only.", + "expected_output": "A grouped summary that preserves the five meaningful categories, merges overlap, and drops typo-level noise.", + "expectations": [ + "Highlights distinct meaningful efforts instead of forcing one dominant umbrella theme", + "Retains only distinct high-signal change groups", + "Does not collapse several unique top-level efforts into one stitched sentence", + "Outputs grouped lines only" + ] } ] } From 165871e2f709388be832c8e3a40babcfde379ff1 Mon Sep 17 00:00:00 2001 From: "aicia[bot]" Date: Mon, 16 Mar 2026 22:53:00 +0100 Subject: [PATCH 09/23] =?UTF-8?q?=F0=9F=94=A8=20validate=20grouped=20squas?= =?UTF-8?q?h=20summary=20rules?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Update squash summary checks so the validator expects grouped lines, distinct effort preservation, and the new anti-stitching wording instead of a single subject line. --- scripts/validate-skill-templates.ps1 | 24 +++++++++++++----------- 1 file changed, 13 insertions(+), 11 deletions(-) diff --git a/scripts/validate-skill-templates.ps1 b/scripts/validate-skill-templates.ps1 index e5b0d39..d95bc53 100644 --- a/scripts/validate-skill-templates.ps1 +++ b/scripts/validate-skill-templates.ps1 @@ -662,18 +662,19 @@ Add-ValidationResult -Results $results -Name 'Git visual squash summary skill st throw 'git-visual commit-language references must stay byte-for-byte identical' } - Assert-Contains -Name 'git-visual-squash-summary/SKILL.md' -Content $skill -Needle 'This skill turns a stack of commits into one squash-ready subject line' + 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 'detects the dominant theme' + 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 '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 bullet-list summary.' - Assert-Contains -Name 'git-visual-squash-summary/SKILL.md' -Content $skill -Needle 'Return a subject line only, never a body.' - Assert-Contains -Name 'git-visual-squash-summary/SKILL.md' -Content $skill -Needle 'Keep the subject at or below 72 characters.' + 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 'Fits naturally in the squash merge commit field on GitHub.' + 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.' - Assert-Contains -Name 'git-visual-squash-summary/SKILL.md' -Content $skill -Needle 'Output the finished squash-ready subject line and stop.' + Assert-Contains -Name 'git-visual-squash-summary/SKILL.md' -Content $skill -Needle 'Output the finished grouped summary lines and stop.' Assert-Contains -Name 'git-visual-squash-summary/SKILL.md' -Content $skill -Needle '`git bot commit`, `git add`, or any other mutating command.' Assert-NotContains -Name 'git-visual-squash-summary/SKILL.md' -Content $skill -Needle '' Assert-NotContains -Name 'git-visual-squash-summary/SKILL.md' -Content $skill -Needle 'The body is usually 1-4 wrapped lines' @@ -682,12 +683,13 @@ Add-ValidationResult -Results $results -Name 'Git visual squash summary skill st Assert-Contains -Name 'git-visual-squash-summary/references/commit-language.md' -Content $commitLanguage -Needle 'Gitmoji First, Fallback Second' Assert-Contains -Name 'git-visual-squash-summary/evals/evals.json' -Content $evals -Needle 'Does not run mutating git commands' - Assert-Contains -Name 'git-visual-squash-summary/evals/evals.json' -Content $evals -Needle 'Detects and centers the dominant theme of the commit stack' + Assert-Contains -Name 'git-visual-squash-summary/evals/evals.json' -Content $evals -Needle 'Retains only distinct high-signal change groups' Assert-Contains -Name 'git-visual-squash-summary/evals/evals.json' -Content $evals -Needle 'Reads like a curated human-written condensed history rather than a dump of commit subjects' Assert-Contains -Name 'git-visual-squash-summary/evals/evals.json' -Content $evals -Needle 'Favors readable GitHub and terminal output' - Assert-Contains -Name 'git-visual-squash-summary/evals/evals.json' -Content $evals -Needle 'Returns a subject only and never adds a body' - Assert-Contains -Name 'git-visual-squash-summary/evals/evals.json' -Content $evals -Needle 'Keeps the subject at or below 72 characters' - Assert-Contains -Name 'git-visual-squash-summary/evals/evals.json' -Content $evals -Needle 'Does not treat the result as a changelog entry' + Assert-Contains -Name 'git-visual-squash-summary/evals/evals.json' -Content $evals -Needle 'Returns grouped lines only and never adds a title or body' + Assert-Contains -Name 'git-visual-squash-summary/evals/evals.json' -Content $evals -Needle 'Keeps every output line at or below 72 characters' + 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' } From 5471b4d8778e1286452a6185738a71a5a58e5e4f Mon Sep 17 00:00:00 2001 From: "aicia[bot]" Date: Mon, 16 Mar 2026 22:53:05 +0100 Subject: [PATCH 10/23] =?UTF-8?q?=F0=9F=93=9D=20docs:=20describe=20grouped?= =?UTF-8?q?=20squash=20summaries?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Refresh the README so git-visual-squash-summary is presented as a grouped-summary companion that keeps distinct efforts visible instead of collapsing everything into one subject. --- README.md | 23 ++++++++++++----------- 1 file changed, 12 insertions(+), 11 deletions(-) diff --git a/README.md b/README.md index d32473c..55fb6f8 100644 --- a/README.md +++ b/README.md @@ -69,7 +69,7 @@ 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-visual-squash-summary](skills/git-visual-squash-summary/SKILL.md) | Non-mutating squash-subject companion to `git-visual-commits`. Turns noisy commit stacks into one polished squash-ready subject line for the GitHub squash merge field, detecting the dominant theme, preserving technical identifiers, favoring readable GitHub/terminal output, 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 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. | | [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. | | [dotnet-new-app-slnx](skills/dotnet-new-app-slnx/SKILL.md) | Scaffold a new .NET standalone application solution following codebeltnet engineering conventions. Supports Console, Web, and Worker host families with Startup or Minimal hosting patterns; Web expands into Empty Web, Web API, MVC, or Web App / Razor, plus functional tests and a simplified CI pipeline. | | [trunk-first-repo](skills/trunk-first-repo/SKILL.md) | Initialize a git repository following [scaled trunk-based development](https://trunkbaseddevelopment.com/#scaled-trunk-based-development). Seeds an empty `main` branch and creates a versioned feature branch (`v0.1.0/init`), enforcing a PR-first workflow where content only reaches main through peer-reviewed pull requests. | @@ -140,20 +140,21 @@ Commit messages are the most-read documentation in any codebase — yet they're ### Why git-visual-squash-summary? Sometimes the history is already written and the only thing you need is -the final squash subject. A long branch with fixups, rename follow-ups, -review nits, and repeated attempts often has a clean net effect but a -messy chronological story. That is where **git-visual-squash-summary** -fits: it reads the real history and diff, then compresses them into one -truthful squash-ready subject line. +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` -- **Subject-only by design** — returns the subject line only, never a body +- **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 -- **Dominant-theme first** — picks the main story instead of listing every sub-change -- **Intent over chronology** — collapses noisy commit stacks into the net effect +- **Distinct efforts stay distinct** — preserves meaningful change groups instead of forcing one umbrella line +- **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 - **Identifier-safe wording** — preserves technical names, paths, flags, and types where possible -- **Readable in GitHub and terminals** — optimized for the squash merge field and compact commit views -- **Strict 72-char subject** — ready for teams that want compact squash summaries +- **Readable in GitHub and terminals** — optimized for compact PR and squash-summary views +- **Strict 72-char lines** — every summary line stays compact and scannable - **Not a changelog** — avoids release-note phrasing and commit-subject dumps - **No unsupported claims** — summarizes only what the inspected diff can justify From 4984456d3b422b9a066506d7f69f8bac839e8e8f Mon Sep 17 00:00:00 2001 From: "aicia[bot]" Date: Mon, 16 Mar 2026 23:44:57 +0100 Subject: [PATCH 11/23] =?UTF-8?q?=E2=9C=A8=20add=20git-keep-a-changelog=20?= =?UTF-8?q?skill?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add a git-aware Keep a Changelog skill that creates or updates CHANGELOG.md from the current branch by default, reads full commit bodies for context, infers release headings from branch version hints, and writes a required SemVer-aware release highlight with natural prose. --- skills/git-keep-a-changelog/SKILL.md | 209 +++++++++++++++++++ skills/git-keep-a-changelog/evals/evals.json | 61 ++++++ 2 files changed, 270 insertions(+) create mode 100644 skills/git-keep-a-changelog/SKILL.md create mode 100644 skills/git-keep-a-changelog/evals/evals.json diff --git a/skills/git-keep-a-changelog/SKILL.md b/skills/git-keep-a-changelog/SKILL.md new file mode 100644 index 0000000..d933eb9 --- /dev/null +++ b/skills/git-keep-a-changelog/SKILL.md @@ -0,0 +1,209 @@ +--- +name: git-keep-a-changelog +description: > + Create or update CHANGELOG.md from git history using Keep a Changelog + 1.1.0 style. Use this skill whenever the user asks to create or update + the changelog, draft release notes from the current branch, summarize commits into + Added/Changed/Fixed style sections, or mentions Keep a Changelog, + CHANGELOG.md, release highlights, or SemVer-aware release summaries. + Treat requests like "create the changelog", "update the changelog", + "write release notes from git", "draft the changelog for this branch", + or "summarize these commits into CHANGELOG.md" as automatic triggers. + This skill reads full commit subjects and bodies plus the net diff, + infers a version heading from the branch when possible, creates a + compliant changelog when missing, writes a required SemVer-aware + release highlight, edits CHANGELOG.md directly for review, preserves + natural prose wrapping, and avoids raw commit-log dumps or unsupported + claims. +--- + +# Git Keep A Changelog + +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. + +## Non-Negotiable Rules + +- Update `CHANGELOG.md` directly, then stop for user review. +- If `CHANGELOG.md` does not exist, create a compliant one before + populating it. +- Read full commit subjects and bodies before writing the changelog. +- Inspect the net diff too; do not infer the release from subjects alone. +- If the current branch starts with a version hint such as `v0.3.0/`, + use that to target a concrete release heading. +- Otherwise, target `## [Unreleased]`. +- Always write a release highlight immediately below the target heading. +- 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. +- Preserve natural line breaks and readable prose. Do not hard-wrap + paragraphs to 72 characters. +- Do not dump commit subjects verbatim into the changelog. +- Do not invent unsupported changes, risks, or migration guidance. + +## Release Highlight Contract + +Every updated changelog entry must begin with a short human-written +highlight paragraph directly below the heading. + +That highlight must: + +- act as the TL;DR for the release +- explicitly say whether this is a `major`, `minor`, or `patch` release +- summarize the net effect of the populated sections +- reflect the full commit bodies and net diff, not just the subjects + +Example shape: + +```md +## [0.3.0] - 2026-03-16 + +This is a minor release focused on grouped git visual summaries, +validator hardening, and clearer changelog automation guidance. + +### Added +... +``` + +When the history clearly carries migration risk or upgrade caveats, add +an advisory block such as: + +```md +> [!WARNING] +> Upgrading to this release requires ... +``` + +Only add callouts when the commits or diff justify them. + +## Workflow + +### Step 1: Resolve the source range + +Use the most explicit range the user gave you. + +- If the user named a range, branch comparison, base branch, or PR range, + use that. +- Otherwise, compare the current branch to its upstream merge-base. +- If no upstream is configured, try `main`, then `master`. +- If no safe comparison point can be established, stop and ask for a + base branch or range instead of guessing. + +Helpful commands: + +```bash +git status --short --branch +git rev-parse --abbrev-ref HEAD +git rev-parse --abbrev-ref --symbolic-full-name @{upstream} +git merge-base HEAD @{upstream} +git merge-base HEAD main +git merge-base HEAD master +``` + +### Step 2: Resolve the changelog target + +Determine whether to write a concrete release section or update +`[Unreleased]`. + +- If the branch name starts with a version prefix such as + `v0.3.0/feature-name`, target `## [0.3.0] - YYYY-MM-DD`. +- Strip the leading `v` from the visible changelog heading, but keep tag + comparisons in `vX.Y.Z` form. +- 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 + +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. +- Prefer the final user-visible or maintainer-meaningful outcome over the + implementation path. + +Helpful commands: + +```bash +git log --reverse --format=medium +git log --reverse --stat --format=medium +git diff --stat ..HEAD +git diff ..HEAD +``` + +### Step 4: Classify the release + +Infer the SemVer class from the actual change set. + +- `major` when the release includes breaking removals, required migration, + incompatible contract changes, or other true breaking behavior. +- `minor` when the release adds meaningful new capabilities without + breaking existing consumers. +- `patch` when the release is primarily fixes, service updates, docs, + validation, maintenance, dependency work, or other non-breaking + refinement. + +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 + +Write the release highlight first, then the populated sections. + +- Map the net effect into `Added`, `Changed`, `Deprecated`, `Removed`, + `Fixed`, and `Security`. +- Keep bullets curated and human-written. +- Merge overlapping commits into one bullet when they describe the same + real outcome. +- Drop low-signal churn such as typo-only commits, trivial fixups, or + mechanical follow-ups unless they materially change the release story. +- Use natural prose line breaks. Keep paragraphs and bullets readable, but + do not column-wrap them artificially. + +### Step 6: Update CHANGELOG.md carefully + +Preserve the file's existing structure while editing. + +- If `CHANGELOG.md` is missing, create it with the standard title, + intro paragraph, `## [Unreleased]`, and compare-link footer before + inserting release content. +- 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. +- Do not remove existing links or historical entries unless they are + demonstrably wrong. + +### Step 7: 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. + +## Good Output Characteristics + +- Reads like a curated release narrative, not a generated log dump. +- Uses the Keep a Changelog section order consistently. +- 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. +- Preserves natural prose wrapping instead of forcing narrow columns. +- Keeps bullets specific, concrete, and non-repetitive. +- Preserves existing compare-link structure when updating versions. + +## Bad Output Characteristics + +- Copying commit subjects line by line into the changelog. +- 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. +- Using artificial 72-character wrapping for changelog prose. +- Emitting empty `Added` / `Changed` / `Fixed` headings. +- Claiming breaking changes, fixes, or security work not supported by git. diff --git a/skills/git-keep-a-changelog/evals/evals.json b/skills/git-keep-a-changelog/evals/evals.json new file mode 100644 index 0000000..2d3c1cc --- /dev/null +++ b/skills/git-keep-a-changelog/evals/evals.json @@ -0,0 +1,61 @@ +{ + "skill_name": "git-keep-a-changelog", + "evals": [ + { + "id": 1, + "prompt": "Update CHANGELOG.md for the current branch using Keep a Changelog. Use the current branch by default, read the full commit messages, and update the file directly for my review.", + "expected_output": "CHANGELOG.md is updated in place using the current branch comparison, with a curated release highlight and standard Keep a Changelog sections.", + "expectations": [ + "Updates CHANGELOG.md directly instead of only drafting notes in chat", + "Reads full commit subjects and bodies before writing the release entry", + "Uses the current branch versus merge-base as the default source when no explicit range is given", + "Writes a required release highlight before the section headings", + "Stops after editing the changelog for user review" + ] + }, + { + "id": 2, + "prompt": "My branch is named v0.3.0/new-complementary-skills. Update CHANGELOG.md from git history and use that branch hint if applicable.", + "expected_output": "A concrete release heading is created or updated from the branch version hint, with compare links adjusted consistently.", + "expectations": [ + "Treats a leading branch version such as v0.3.0/ as a release hint", + "Uses a visible changelog heading without the leading v", + "Updates compare links when adding a concrete release section", + "Falls back to Unreleased only when no branch version hint exists" + ] + }, + { + "id": 3, + "prompt": "Update the changelog, but use the full commit messages for context. Some commit bodies explain migration risk that is not obvious from the subject line.", + "expected_output": "The changelog reflects details from commit bodies, including release classification and any justified upgrade warning or important note.", + "expectations": [ + "Uses full commit bodies rather than relying on subject lines alone", + "Infers the SemVer class from the actual change set", + "Adds an advisory block only when the commits or diff justify it", + "Does not invent unsupported migration guidance" + ] + }, + { + "id": 4, + "prompt": "Please update CHANGELOG.md in Keep a Changelog style, but do not hard-wrap the prose. I want natural line breaks that read well for humans.", + "expected_output": "The changelog is updated with natural prose line breaks instead of artificial narrow wrapping.", + "expectations": [ + "Preserves natural prose wrapping instead of forcing 72-character lines", + "Uses the standard Keep a Changelog section order", + "Omits empty sections instead of inserting placeholders", + "Avoids dumping raw commit subjects verbatim" + ] + }, + { + "id": 5, + "prompt": "There is no CHANGELOG.md yet. Create one in Keep a Changelog style from the current branch commits, including the release highlight and the standard scaffold.", + "expected_output": "A new compliant CHANGELOG.md is created and populated from git history instead of failing due to the missing file.", + "expectations": [ + "Creates CHANGELOG.md when it does not already exist", + "Seeds the file with the standard title, intro, and Unreleased heading", + "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" + ] + } + ] +} From 358800bede90475b2e803aaf4197eb213f904d52 Mon Sep 17 00:00:00 2001 From: "aicia[bot]" Date: Mon, 16 Mar 2026 23:45:04 +0100 Subject: [PATCH 12/23] =?UTF-8?q?=F0=9F=94=A8=20validate=20git=20keep=20a?= =?UTF-8?q?=20changelog=20rules?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add deterministic checks for the changelog skill so the repo enforces full-commit context, branch-version hints, SemVer-aware highlights, natural prose, and missing-file creation behavior. --- scripts/validate-skill-templates.ps1 | 26 ++++++++++++++++++++++++++ 1 file changed, 26 insertions(+) diff --git a/scripts/validate-skill-templates.ps1 b/scripts/validate-skill-templates.ps1 index d95bc53..223ce06 100644 --- a/scripts/validate-skill-templates.ps1 +++ b/scripts/validate-skill-templates.ps1 @@ -693,6 +693,32 @@ 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 invent unsupported changes' } +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 + $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 'Update `CHANGELOG.md` directly, then stop for user review.' + Assert-Contains -Name 'git-keep-a-changelog/SKILL.md' -Content $skill -Needle 'If `CHANGELOG.md` does not exist, create a compliant one before' + Assert-Contains -Name 'git-keep-a-changelog/SKILL.md' -Content $skill -Needle 'Read full commit subjects and bodies before writing the changelog.' + Assert-Contains -Name 'git-keep-a-changelog/SKILL.md' -Content $skill -Needle 'If the current branch starts with a version hint such as `v0.3.0/`,' + 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 '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 hard-wrap' + 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 'Do not commit, tag, push, or create a release unless the user asks.' + + 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' + Assert-Contains -Name 'git-keep-a-changelog/evals/evals.json' -Content $evals -Needle 'Uses full commit bodies rather than relying on subject lines alone' + Assert-Contains -Name 'git-keep-a-changelog/evals/evals.json' -Content $evals -Needle 'Preserves natural prose wrapping instead of forcing 72-character lines' + Assert-Contains -Name 'git-keep-a-changelog/evals/evals.json' -Content $evals -Needle 'Creates CHANGELOG.md when it does not already exist' +} + Add-ValidationResult -Results $results -Name 'Rendered app worker template leaves no unexpected placeholders' -Action { $files = @( 'skills/dotnet-new-app-slnx/assets/shared/Directory.Packages.props', From 878e25a15f36929ce30a57f520e31422e946080b Mon Sep 17 00:00:00 2001 From: "aicia[bot]" Date: Mon, 16 Mar 2026 23:45:11 +0100 Subject: [PATCH 13/23] =?UTF-8?q?=F0=9F=93=9D=20docs:=20describe=20git=20k?= =?UTF-8?q?eep=20a=20changelog?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add install and discovery docs for git-keep-a-changelog, including its create-or-update behavior, SemVer-aware release highlights, and Keep a Changelog focus. --- README.md | 22 ++++++++++++++++++++++ 1 file changed, 22 insertions(+) diff --git a/README.md b/README.md index 55fb6f8..1f015f3 100644 --- a/README.md +++ b/README.md @@ -47,6 +47,7 @@ If you want a bundle of skills always available, just install them all: ```bash npx skills add https://github.com/codebeltnet/agentic --skill git-visual-commits +npx skills add https://github.com/codebeltnet/agentic --skill git-keep-a-changelog npx skills add https://github.com/codebeltnet/agentic --skill git-visual-squash-summary npx skills add https://github.com/codebeltnet/agentic --skill trunk-first-repo npx skills add https://github.com/codebeltnet/agentic --skill dotnet-strong-name-signing @@ -69,6 +70,7 @@ 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-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. | | [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. | | [dotnet-new-app-slnx](skills/dotnet-new-app-slnx/SKILL.md) | Scaffold a new .NET standalone application solution following codebeltnet engineering conventions. Supports Console, Web, and Worker host families with Startup or Minimal hosting patterns; Web expands into Empty Web, Web API, MVC, or Web App / Razor, plus functional tests and a simplified CI pipeline. | @@ -85,6 +87,12 @@ If your Markdown viewer supports code-block copy buttons, each command below sho npx skills add https://github.com/codebeltnet/agentic --skill git-visual-commits ``` +`git-keep-a-changelog` + +```bash +npx skills add https://github.com/codebeltnet/agentic --skill git-keep-a-changelog +``` + `git-visual-squash-summary` ```bash @@ -158,6 +166,20 @@ then compresses them into a small set of truthful grouped lines. - **Not a changelog** — avoids release-note phrasing and commit-subject dumps - **No unsupported claims** — summarizes only what the inspected diff can justify +### Why git-keep-a-changelog? + +Writing `CHANGELOG.md` well is harder than it looks. Raw commit subjects are too noisy, PR titles often miss migration context, and release notes get much better when the writer actually reads the commit bodies and understands the net diff. That is where **git-keep-a-changelog** fits: it turns the current branch into a curated Keep a Changelog entry and creates or updates the file directly for review. + +- **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 +- **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 instead of hard-wrapping changelog text to narrow columns +- **Direct file edit** — creates or updates `CHANGELOG.md` directly, then stops for human review +- **Compare-link aware** — can update bottom-of-file compare links when a concrete release heading is added +- **Not a commit dump** — curates the release story instead of copying git log output into Markdown + ### Why dotnet-new-lib-slnx and dotnet-new-app-slnx? Starting a new .NET solution "from scratch" usually means copying from your last project, deleting half of it, and spending an hour wiring up CI, MSBuild props, versioning, and code quality tooling. Every new repo drifts slightly from the last one. Six months later, no two solutions look the same. From 756a05780c844b9031dd2b52686fb0c8f7022966 Mon Sep 17 00:00:00 2001 From: "aicia[bot]" Date: Mon, 16 Mar 2026 23:55:10 +0100 Subject: [PATCH 14/23] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20refactor:=20relax=20?= =?UTF-8?q?changelog=20formatting=20rules?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Remove fixed-width wrapping guidance from git-keep-a-changelog and require section bullets to end with commas, with the final bullet in each section ending with a period. --- skills/git-keep-a-changelog/SKILL.md | 22 +++++++++++++------- skills/git-keep-a-changelog/evals/evals.json | 5 +++-- 2 files changed, 18 insertions(+), 9 deletions(-) diff --git a/skills/git-keep-a-changelog/SKILL.md b/skills/git-keep-a-changelog/SKILL.md index d933eb9..733707c 100644 --- a/skills/git-keep-a-changelog/SKILL.md +++ b/skills/git-keep-a-changelog/SKILL.md @@ -26,7 +26,7 @@ release-note noise. ## Non-Negotiable Rules -- Update `CHANGELOG.md` directly, then stop for user review. +- Create or update `CHANGELOG.md` directly, then stop for user review. - If `CHANGELOG.md` does not exist, create a compliant one before populating it. - Read full commit subjects and bodies before writing the changelog. @@ -40,8 +40,11 @@ release-note noise. - Use the standard Keep a Changelog section order: `Added`, `Changed`, `Deprecated`, `Removed`, `Fixed`, `Security`. - Omit empty sections instead of emitting placeholders. -- Preserve natural line breaks and readable prose. Do not hard-wrap - paragraphs to 72 characters. +- 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 + `.`. - Do not dump commit subjects verbatim into the changelog. - Do not invent unsupported changes, risks, or migration guidance. @@ -162,7 +165,9 @@ Write the release highlight first, then the populated sections. - Drop low-signal churn such as typo-only commits, trivial fixups, or mechanical follow-ups unless they materially change the release story. - Use natural prose line breaks. Keep paragraphs and bullets readable, but - do not column-wrap them artificially. + 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 @@ -194,8 +199,9 @@ Do not commit, tag, push, or create a release unless the user asks. - 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. -- Preserves natural prose wrapping instead of forcing narrow columns. -- Keeps bullets specific, concrete, and non-repetitive. +- 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. ## Bad Output Characteristics @@ -204,6 +210,8 @@ Do not commit, tag, push, or create a release unless the user asks. - 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. -- Using artificial 72-character wrapping for changelog prose. +- 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. - Claiming breaking changes, fixes, or security work not supported by git. diff --git a/skills/git-keep-a-changelog/evals/evals.json b/skills/git-keep-a-changelog/evals/evals.json index 2d3c1cc..9ace2e3 100644 --- a/skills/git-keep-a-changelog/evals/evals.json +++ b/skills/git-keep-a-changelog/evals/evals.json @@ -40,10 +40,11 @@ "prompt": "Please update CHANGELOG.md in Keep a Changelog style, but do not hard-wrap the prose. I want natural line breaks that read well for humans.", "expected_output": "The changelog is updated with natural prose line breaks instead of artificial narrow wrapping.", "expectations": [ - "Preserves natural prose wrapping instead of forcing 72-character lines", + "Preserves natural prose wrapping instead of forcing any fixed column width", "Uses the standard Keep a Changelog section order", "Omits empty sections instead of inserting placeholders", - "Avoids dumping raw commit subjects verbatim" + "Avoids dumping raw commit subjects verbatim", + "Ends bullets with commas and ends the final bullet in each section with a period" ] }, { From b64d235ee72049394798bf9cb878fc098fdbd36c Mon Sep 17 00:00:00 2001 From: "aicia[bot]" Date: Mon, 16 Mar 2026 23:55:16 +0100 Subject: [PATCH 15/23] =?UTF-8?q?=F0=9F=94=A8=20validate=20changelog=20for?= =?UTF-8?q?matting=20rules?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Update the changelog skill checks to expect natural prose without any fixed-width wrapping target and to enforce the section-bullet comma/period punctuation pattern. --- scripts/validate-skill-templates.ps1 | 8 +++++--- 1 file changed, 5 insertions(+), 3 deletions(-) diff --git a/scripts/validate-skill-templates.ps1 b/scripts/validate-skill-templates.ps1 index 223ce06..5dbd377 100644 --- a/scripts/validate-skill-templates.ps1 +++ b/scripts/validate-skill-templates.ps1 @@ -697,7 +697,7 @@ Add-ValidationResult -Results $results -Name 'Git keep a changelog skill updates $skill = Get-FileText -RepoRoot $repoRoot -RelativePath 'skills/git-keep-a-changelog/SKILL.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 'Update `CHANGELOG.md` directly, then stop for user review.' + Assert-Contains -Name 'git-keep-a-changelog/SKILL.md' -Content $skill -Needle 'Create or update `CHANGELOG.md` directly, then stop for user review.' Assert-Contains -Name 'git-keep-a-changelog/SKILL.md' -Content $skill -Needle 'If `CHANGELOG.md` does not exist, create a compliant one before' Assert-Contains -Name 'git-keep-a-changelog/SKILL.md' -Content $skill -Needle 'Read full commit subjects and bodies before writing the changelog.' Assert-Contains -Name 'git-keep-a-changelog/SKILL.md' -Content $skill -Needle 'If the current branch starts with a version hint such as `v0.3.0/`,' @@ -705,7 +705,8 @@ Add-ValidationResult -Results $results -Name 'Git keep a changelog skill updates 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 '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 hard-wrap' + 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 '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:' @@ -715,7 +716,8 @@ Add-ValidationResult -Results $results -Name 'Git keep a changelog skill updates 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' Assert-Contains -Name 'git-keep-a-changelog/evals/evals.json' -Content $evals -Needle 'Uses full commit bodies rather than relying on subject lines alone' - Assert-Contains -Name 'git-keep-a-changelog/evals/evals.json' -Content $evals -Needle 'Preserves natural prose wrapping instead of forcing 72-character lines' + 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' } From a52aec455ae3110c45b40fe45868a1e57e9e0e30 Mon Sep 17 00:00:00 2001 From: "aicia[bot]" Date: Mon, 16 Mar 2026 23:55:24 +0100 Subject: [PATCH 16/23] =?UTF-8?q?=F0=9F=93=9D=20docs:=20clarify=20changelo?= =?UTF-8?q?g=20formatting=20expectations?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Refresh the git-keep-a-changelog docs so they promise natural prose without fixed-width wrapping and the required bullet punctuation pattern. --- README.md | 3 ++- 1 file changed, 2 insertions(+), 1 deletion(-) diff --git a/README.md b/README.md index 1f015f3..87b343d 100644 --- a/README.md +++ b/README.md @@ -175,7 +175,8 @@ Writing `CHANGELOG.md` well is harder than it looks. Raw commit subjects are too - **Version-aware by branch** — uses a branch prefix like `v0.3.0/...` as the release heading hint when present - **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 instead of hard-wrapping changelog text to narrow columns +- **Natural prose** — preserves human-readable line breaks without any fixed-width wrapping target +- **Predictable bullet punctuation** — bullets end with `,` and the last bullet in each section ends with `.` - **Direct file edit** — creates or updates `CHANGELOG.md` directly, then stops for human review - **Compare-link aware** — can update bottom-of-file compare links when a concrete release heading is added - **Not a commit dump** — curates the release story instead of copying git log output into Markdown From fae21bc97c2048d262df81128adc72eac27639c4 Mon Sep 17 00:00:00 2001 From: "aicia[bot]" Date: Mon, 16 Mar 2026 23:57:43 +0100 Subject: [PATCH 17/23] =?UTF-8?q?=F0=9F=93=9D=20docs:=20normalize=20change?= =?UTF-8?q?log=20prose?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Reflow existing changelog entries into natural prose so the release notes read cleanly in Markdown without narrow manual line wrapping. --- CHANGELOG.md | 48 ++++++++++++++---------------------------------- 1 file changed, 14 insertions(+), 34 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index aa1ecb8..a6293b5 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -11,57 +11,37 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ### Added -- Added per-skill `evals/evals.json` coverage across the repo, including - deterministic validation for scaffold behavior and skill contracts. -- Expanded `dotnet-new-app-slnx` with explicit web-family variants for - Empty Web, Web API, MVC, and Web App / Razor scaffolds. -- Introduced a NuGet-backed app package resolver so generated - `Directory.Packages.props` files use current compatible versions. +- Added per-skill `evals/evals.json` coverage across the repo, including deterministic validation for scaffold behavior and skill contracts. +- Expanded `dotnet-new-app-slnx` with explicit web-family variants for Empty Web, Web API, MVC, and Web App / Razor scaffolds. +- Introduced a NuGet-backed app package resolver so generated `Directory.Packages.props` files use current compatible versions. ### Changed -- Hardened the .NET app and library scaffold skills around required - outputs, current-folder generation, supported TFM choices, and clearer - usage guidance. -- Tightened repo documentation and local skill-sync guidance so README, - policy, and install expectations stay aligned. -- Strengthened `git-visual-commits` with identity lock, `yolo` guardrails, - post-commit verification, and clearer umbrella-commit rejection rules. +- Hardened the .NET app and library scaffold skills around required outputs, current-folder generation, supported TFM choices, and clearer usage guidance. +- Tightened repo documentation and local skill-sync guidance so README, policy, and install expectations stay aligned. +- Strengthened `git-visual-commits` with identity lock, `yolo` guardrails, post-commit verification, and clearer umbrella-commit rejection rules. ### Fixed -- Improved scaffold fidelity so generated assets stay complete, shared - files remain synchronized, and emitted app templates are validation- and - compile-ready. +- Improved scaffold fidelity so generated assets stay complete, shared files remain synchronized, and emitted app templates are validation- and compile-ready. ## [0.1.0] - 2026-03-15 ### Added -- Launched the initial skill suite with `git-visual-commits`, - `trunk-first-repo`, `dotnet-strong-name-signing`, - `dotnet-new-lib-slnx`, and `dotnet-new-app-slnx`. -- Added repo governance and contributor guidance, including the initial - `README`, `CONTRIBUTING`, `AGENTS.md`, license, and ignore rules. -- Added shared scaffold assets for CI, packaging, documentation, - benchmarking, and TFM-aware test environments for the .NET skills. +- Launched the initial skill suite with `git-visual-commits`, `trunk-first-repo`, `dotnet-strong-name-signing`, `dotnet-new-lib-slnx`, and `dotnet-new-app-slnx`. +- Added repo governance and contributor guidance, including the initial `README`, `CONTRIBUTING`, `AGENTS.md`, license, and ignore rules. +- Added shared scaffold assets for CI, packaging, documentation, benchmarking, and TFM-aware test environments for the .NET skills. ### Changed -- Split the original combined .NET scaffolder into dedicated app and - library skills with clearer scope boundaries and lower-friction prompts. -- Refined scaffold defaults to derive more metadata from repo state, - official .NET support data, and current package feeds instead of stale - hardcoded values. -- Evolved `git-visual-commits` from a basic commit helper into an - opinionated workflow with reviewable commit plans, collaborative - attribution modes, richer gitmoji coverage, and body-by-default support. +- Split the original combined .NET scaffolder into dedicated app and library skills with clearer scope boundaries and lower-friction prompts. +- Refined scaffold defaults to derive more metadata from repo state, official .NET support data, and current package feeds instead of stale hardcoded values. +- Evolved `git-visual-commits` from a basic commit helper into an opinionated workflow with reviewable commit plans, collaborative attribution modes, richer gitmoji coverage, and body-by-default support. ### Fixed -- Improved scaffold fidelity with hidden `.bot` asset preservation, - explicit UTF-8 and BOM handling, and checks aimed at preventing mojibake - or incomplete generated output. +- 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.2.0...HEAD [0.2.0]: https://github.com/codebeltnet/agentic/compare/v0.1.0...v0.2.0 From 35ab38ee008ead4ce1b7395454b74fd709d03251 Mon Sep 17 00:00:00 2001 From: "aicia[bot]" Date: Tue, 17 Mar 2026 00:00:33 +0100 Subject: [PATCH 18/23] =?UTF-8?q?=F0=9F=93=9D=20docs:=20add=200.3.0=20chan?= =?UTF-8?q?gelog=20entry?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Capture the 0.3.0 release in CHANGELOG.md with a SemVer-aware release highlight, curated Added and Changed sections, and updated compare links for the new version. --- CHANGELOG.md | 21 ++++++++++++++++++++- 1 file changed, 20 insertions(+), 1 deletion(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index a6293b5..b07360b 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -7,6 +7,24 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [Unreleased] +## [0.3.0] - 2026-03-17 + +This is a minor release that introduces two complementary git workflow skills, extracts a shared commit-language reference, and backs the whole skill suite with CI-enforced template validation. + +### Added + +- `git-visual-squash-summary` skill that turns a noisy commit stack into grouped summary lines — preserving distinct high-signal efforts, merging overlapping commits, and dropping low-signal noise — without mutating git state, +- `git-keep-a-changelog` skill that creates or updates `CHANGELOG.md` directly from the current branch, reads full commit message bodies for context, infers release headings from branch version hints, and writes a required SemVer-aware release highlight with natural prose, +- GitHub Actions workflow that runs `validate-skill-templates.ps1` on every push and pull request as the merge safety net, +- Per-skill `evals/evals.json` coverage for `git-visual-squash-summary` and `git-keep-a-changelog`. + +### Changed + +- Extracted the shared commit-language guidance into `references/commit-language.md`, used by both `git-visual-commits` and `git-visual-squash-summary`, so prefix, emoji, and wording rules have one maintained source, +- Tightened `git-visual-commits` grouping rules to classify new repo capabilities, existing-skill refactors, and shared-reference sync as separate intents, with eval coverage for mixed-diff cases, +- Hardened `validate-skill-templates.ps1` with UTF-8 and BOM handling, grouped squash summary rule checks, changelog formatting enforcement, and consistent behavior across Windows PowerShell and CI, +- Updated `CONTRIBUTING.md` to explain the local-first validation workflow: run the script locally for fast feedback while GitHub Actions reruns the same checks as the safety net. + ## [0.2.0] - 2026-03-16 ### Added @@ -43,6 +61,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 - 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.2.0...HEAD +[Unreleased]: https://github.com/codebeltnet/agentic/compare/v0.3.0...HEAD +[0.3.0]: https://github.com/codebeltnet/agentic/compare/v0.2.0...v0.3.0 [0.2.0]: https://github.com/codebeltnet/agentic/compare/v0.1.0...v0.2.0 [0.1.0]: https://github.com/codebeltnet/agentic/compare/7eaf364...v0.1.0 From e25afe2ac391aba1a78cc9c02baefbe0f36cc8e7 Mon Sep 17 00:00:00 2001 From: "aicia[bot]" Date: Tue, 17 Mar 2026 00:03:27 +0100 Subject: [PATCH 19/23] =?UTF-8?q?=F0=9F=94=A8=20run=20skill=20validation?= =?UTF-8?q?=20on=20pull=20requests=20only?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Limit the validation workflow to pull requests to avoid duplicate push and pull_request checks, and update the contributor docs to describe the PR-only safety net accurately. --- .github/workflows/validate-skill-templates.yml | 1 - CONTRIBUTING.md | 2 +- README.md | 4 ++-- 3 files changed, 3 insertions(+), 4 deletions(-) diff --git a/.github/workflows/validate-skill-templates.yml b/.github/workflows/validate-skill-templates.yml index dd0df8a..f214b4f 100644 --- a/.github/workflows/validate-skill-templates.yml +++ b/.github/workflows/validate-skill-templates.yml @@ -2,7 +2,6 @@ name: Validate Skill Templates on: pull_request: - push: jobs: validate-skill-templates: diff --git a/CONTRIBUTING.md b/CONTRIBUTING.md index fc03995..38f6094 100644 --- a/CONTRIBUTING.md +++ b/CONTRIBUTING.md @@ -107,7 +107,7 @@ powershell -NoProfile -ExecutionPolicy Bypass -File .\scripts\validate-skill-tem ``` Run the validator locally first for the fastest feedback loop. GitHub -Actions also runs the same script on pushes and pull requests, but CI is +Actions also runs the same script on pull requests, but CI is the backstop, not the primary authoring loop. To compare a change against the initial imported version, run the same harness against a git ref: diff --git a/README.md b/README.md index 87b343d..aec49b0 100644 --- a/README.md +++ b/README.md @@ -16,8 +16,8 @@ One more consistency rule matters for form-driven skills: native input fields ar Validation follows the same philosophy: run `scripts/validate-skill-templates.ps1` locally for the fast feedback -loop, and let GitHub Actions rerun that same script on pushes and pull -requests as the safety net. +loop, and let GitHub Actions rerun that same script on pull requests as +the safety net. ## Install a skill From 2e83bdc149ddced7be7d11b405579ec0f94df6f7 Mon Sep 17 00:00:00 2001 From: "aicia[bot]" Date: Tue, 17 Mar 2026 00:16:57 +0100 Subject: [PATCH 20/23] =?UTF-8?q?=E2=99=BB=EF=B8=8F=20refactor:=20tighten?= =?UTF-8?q?=20git=20skill=20metadata?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Trim git skill frontmatter descriptions to satisfy the repo metadata limit and replace stale "below" wording with direct references to references/commit-language.md. --- skills/git-visual-commits/SKILL.md | 29 ++++++++++------------- skills/git-visual-squash-summary/SKILL.md | 6 ++--- 2 files changed, 15 insertions(+), 20 deletions(-) diff --git a/skills/git-visual-commits/SKILL.md b/skills/git-visual-commits/SKILL.md index dca4d72..b8ccb33 100644 --- a/skills/git-visual-commits/SKILL.md +++ b/skills/git-visual-commits/SKILL.md @@ -1,23 +1,18 @@ --- name: git-visual-commits description: > - Rules and workflow for creating well-structured git commits using emoji - prefixes (gitmoji and beyond), with support for git bot commit - (AI-authored), regular git commit (human-authored), and git our commit - (collaborative — agent analyzes authorship and human picks attribution). + 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 things like "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 — when the user says "yolo" or "auto" in their - request, or enables it for the session, the agent shows the commit plan - but proceeds without waiting for confirmation. Enforces conventions with - emoji plus lowercase prefix (init, content, style, fix, refactor, docs), - max 70 chars, one logical change per commit, grouped by technology type - with mandatory identity verification after commit. + 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. --- # Git Visual Commits @@ -146,8 +141,8 @@ Never add or modify git remotes. Never set `git user.name` or `git user.email` l ``` -- **Emoji** comes first — picked from the technology/type tables below -- **Prefix** is lowercase (see allowed prefixes below) — **never use `feat:`** +- **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) - **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). - One logical change per commit — don't bundle unrelated things diff --git a/skills/git-visual-squash-summary/SKILL.md b/skills/git-visual-squash-summary/SKILL.md index b165fde..e5642d8 100644 --- a/skills/git-visual-squash-summary/SKILL.md +++ b/skills/git-visual-squash-summary/SKILL.md @@ -1,12 +1,12 @@ --- name: git-visual-squash-summary description: > - Turn many commits into a curated grouped squash summary that - stays compatible with the opinionated wording style of + 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 actually committing. + 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 From 172fee0a734215d02c9ce7f382083fa15ca73200 Mon Sep 17 00:00:00 2001 From: "aicia[bot]" Date: Tue, 17 Mar 2026 00:17:05 +0100 Subject: [PATCH 21/23] =?UTF-8?q?=F0=9F=94=A8=20validate=20skill=20frontma?= =?UTF-8?q?tter=20descriptions?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Add a repo-wide check that normalizes folded YAML descriptions and fails when any skill frontmatter description exceeds the 1024-character limit. --- scripts/validate-skill-templates.ps1 | 30 ++++++++++++++++++++++++++++ 1 file changed, 30 insertions(+) diff --git a/scripts/validate-skill-templates.ps1 b/scripts/validate-skill-templates.ps1 index 5dbd377..86aabee 100644 --- a/scripts/validate-skill-templates.ps1 +++ b/scripts/validate-skill-templates.ps1 @@ -288,6 +288,36 @@ Add-ValidationResult -Results $results -Name 'All repo-managed skills include va } } +Add-ValidationResult -Results $results -Name 'All repo-managed skills keep YAML frontmatter descriptions within 1024 characters' -Action { + $skillRoot = Join-Path $repoRoot 'skills' + $skillDirectories = Get-ChildItem -Path $skillRoot -Directory | Sort-Object Name + + foreach ($skillDir in $skillDirectories) { + $skillRelativePath = ('skills/{0}/SKILL.md' -f $skillDir.Name) + $skill = Get-FileText -RepoRoot $repoRoot -RelativePath $skillRelativePath -GitRef $Ref + + if ($skill -notmatch '(?ms)^---\r?\n(?.*?)\r?\n---') { + throw "$skillRelativePath must include YAML frontmatter delimited by ---" + } + + $frontmatter = $matches['frontmatter'] + if ($frontmatter -notmatch '(?ms)^description:\s*>\s*\r?\n(?(?:[ \t].*\r?\n?)*)') { + throw "$skillRelativePath must include a folded YAML description block" + } + + $descriptionLines = @( + $matches['description'] -split '\r?\n' | + ForEach-Object { $_.Trim() } | + Where-Object { $_ -ne '' } + ) + + $description = [string]::Join(' ', $descriptionLines) + if ($description.Length -gt 1024) { + throw "$skillRelativePath frontmatter description must be 1024 characters or fewer; found $($description.Length)" + } + } +} + Add-ValidationResult -Results $results -Name 'App skill collects target framework and conditional web_variant' -Action { $forms = Get-FileText -RepoRoot $repoRoot -RelativePath 'skills/dotnet-new-app-slnx/FORMS.md' -GitRef $Ref Assert-Contains -Name 'dotnet-new-app-slnx/FORMS.md' -Content $forms -Needle '### target_framework' From c73f411724d5d9de7025eb22f51cd5c16035ce3b Mon Sep 17 00:00:00 2001 From: "aicia[bot]" Date: Tue, 17 Mar 2026 00:17:13 +0100 Subject: [PATCH 22/23] =?UTF-8?q?=F0=9F=93=9D=20docs:=20align=20validation?= =?UTF-8?q?=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Document the new frontmatter metadata validation in the README and fix v0.3.0 release notes so the changelog matches the current pull-request-only validation workflow. --- CHANGELOG.md | 2 +- README.md | 3 ++- 2 files changed, 3 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index b07360b..bfb045e 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -15,7 +15,7 @@ This is a minor release that introduces two complementary git workflow skills, e - `git-visual-squash-summary` skill that turns a noisy commit stack into grouped summary lines — preserving distinct high-signal efforts, merging overlapping commits, and dropping low-signal noise — without mutating git state, - `git-keep-a-changelog` skill that creates or updates `CHANGELOG.md` directly from the current branch, reads full commit message bodies for context, infers release headings from branch version hints, and writes a required SemVer-aware release highlight with natural prose, -- GitHub Actions workflow that runs `validate-skill-templates.ps1` on every push and pull request as the merge safety net, +- GitHub Actions workflow that runs `validate-skill-templates.ps1` on pull requests as the merge safety net, - Per-skill `evals/evals.json` coverage for `git-visual-squash-summary` and `git-keep-a-changelog`. ### Changed diff --git a/README.md b/README.md index aec49b0..0c0047e 100644 --- a/README.md +++ b/README.md @@ -17,7 +17,8 @@ One more consistency rule matters for form-driven skills: native input fields ar Validation follows the same philosophy: run `scripts/validate-skill-templates.ps1` locally for the fast feedback loop, and let GitHub Actions rerun that same script on pull requests as -the safety net. +the safety net. That validator also checks skill frontmatter metadata +such as the 1024-character YAML description limit. ## Install a skill From 601f6dd15e1ddfe6add96ef7576bcf628a2b2b50 Mon Sep 17 00:00:00 2001 From: "aicia[bot]" Date: Tue, 17 Mar 2026 00:19:16 +0100 Subject: [PATCH 23/23] =?UTF-8?q?=F0=9F=93=9D=20docs:=20refine=200.3.0=20c?= =?UTF-8?q?hangelog=20notes?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Refine the 0.3.0 release notes so the summary and Changed section capture the metadata-limit fix, stale git-skill reference cleanup, and the repo-wide frontmatter validation rule. --- CHANGELOG.md | 5 +++-- 1 file changed, 3 insertions(+), 2 deletions(-) diff --git a/CHANGELOG.md b/CHANGELOG.md index bfb045e..41f752a 100644 --- a/CHANGELOG.md +++ b/CHANGELOG.md @@ -9,7 +9,7 @@ and this project adheres to [Semantic Versioning](https://semver.org/spec/v2.0.0 ## [0.3.0] - 2026-03-17 -This is a minor release that introduces two complementary git workflow skills, extracts a shared commit-language reference, and backs the whole skill suite with CI-enforced template validation. +This is a minor release that introduces two complementary git workflow skills, extracts a shared commit-language reference, and backs the whole skill suite with pull-request validation plus stricter skill metadata checks. ### Added @@ -21,8 +21,9 @@ This is a minor release that introduces two complementary git workflow skills, e ### Changed - Extracted the shared commit-language guidance into `references/commit-language.md`, used by both `git-visual-commits` and `git-visual-squash-summary`, so prefix, emoji, and wording rules have one maintained source, +- Tightened git skill metadata so frontmatter descriptions stay within the repo limit and `git-visual-commits` points directly at `references/commit-language.md` instead of stale in-file “below” references, - Tightened `git-visual-commits` grouping rules to classify new repo capabilities, existing-skill refactors, and shared-reference sync as separate intents, with eval coverage for mixed-diff cases, -- Hardened `validate-skill-templates.ps1` with UTF-8 and BOM handling, grouped squash summary rule checks, changelog formatting enforcement, and consistent behavior across Windows PowerShell and CI, +- Hardened `validate-skill-templates.ps1` with UTF-8 and BOM handling, grouped squash summary rule checks, changelog formatting enforcement, repo-wide frontmatter description-length enforcement, and consistent behavior across Windows PowerShell and CI, - Updated `CONTRIBUTING.md` to explain the local-first validation workflow: run the script locally for fast feedback while GitHub Actions reruns the same checks as the safety net. ## [0.2.0] - 2026-03-16