From 312de2beef7f9d9932fdbe041cee6c19da8fe91f Mon Sep 17 00:00:00 2001 From: Waren Gonzaga Date: Wed, 30 Sep 2026 12:05:19 +0800 Subject: [PATCH 1/3] =?UTF-8?q?=F0=9F=93=A6=20new:=20add=20installable=20c?= =?UTF-8?q?lean-commit=20skill=20(#12)?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit * ๐Ÿ“ฆ new: add installable clean-commit skill * ๐Ÿงช test: record standalone skill discovery without clean workflow --- .agents/plugins/marketplace.json | 20 ++++++ .codex-plugin/plugin.json | 32 +++++++++ README.md | 68 +++++++++++++++++++ skills/clean-commit/SKILL.md | 108 +++++++++++++++++++++++++++++++ tests/skill-scenarios.md | 82 +++++++++++++++++++++++ 5 files changed, 310 insertions(+) create mode 100644 .agents/plugins/marketplace.json create mode 100644 .codex-plugin/plugin.json create mode 100644 skills/clean-commit/SKILL.md create mode 100644 tests/skill-scenarios.md diff --git a/.agents/plugins/marketplace.json b/.agents/plugins/marketplace.json new file mode 100644 index 0000000..47d7859 --- /dev/null +++ b/.agents/plugins/marketplace.json @@ -0,0 +1,20 @@ +{ + "name": "clean-commit", + "interface": { + "displayName": "Clean Commit" + }, + "plugins": [ + { + "name": "clean-commit", + "source": { + "source": "local", + "path": "./" + }, + "policy": { + "installation": "AVAILABLE", + "authentication": "ON_INSTALL" + }, + "category": "Productivity" + } + ] +} diff --git a/.codex-plugin/plugin.json b/.codex-plugin/plugin.json new file mode 100644 index 0000000..6c178f7 --- /dev/null +++ b/.codex-plugin/plugin.json @@ -0,0 +1,32 @@ +{ + "name": "clean-commit", + "version": "0.1.0", + "description": "Draft, validate, and create commit messages from the actual Git changes.", + "author": { + "name": "WG Technology Labs", + "url": "https://github.com/wgtechlabs" + }, + "homepage": "https://github.com/wgtechlabs/clean-commit", + "repository": "https://github.com/wgtechlabs/clean-commit", + "license": "MIT", + "keywords": [ + "commits", + "workflow", + "skills" + ], + "skills": "./skills/", + "interface": { + "displayName": "Clean Commit", + "shortDescription": "Write and validate Clean Commit messages", + "longDescription": "Draft, validate, and create commit messages from the actual Git changes.", + "developerName": "WG Technology Labs", + "category": "Productivity", + "capabilities": [ + "Instructions" + ], + "websiteURL": "https://github.com/wgtechlabs/clean-commit", + "defaultPrompt": [ + "Use $clean-commit to draft a message for my staged changes without committing." + ] + } +} diff --git a/README.md b/README.md index 0e86f8f..60dcfad 100644 --- a/README.md +++ b/README.md @@ -13,6 +13,74 @@ A minimalist git commit workflow designed to be simple, memorable, and universal --- +## Install the agent skill + +Use **Clean Commit** on its own, like the standalone +[Clean Coding](https://github.com/wgtechlabs/clean-coding) and +[Clean Code Review](https://github.com/wgtechlabs/clean-code-review) plugins: + +```sh +codex plugin marketplace add wgtechlabs/clean-commit +codex plugin add clean-commit@clean-commit +``` + +Start a new chat and invoke `$clean-commit`, for example: + +```text +$clean-commit draft a message for my staged changes without committing +``` + +For another Agent Skills-compatible host, load the entire +[`skills/clean-commit/`](skills/clean-commit/SKILL.md) folder using that host's skill +installation mechanism. All essential instructions are included; no other +Clean skill is required. The host still needs the tools and access used by the +requested operation. Installation does not authorize repository changes. + +[Clean Workflow](https://github.com/wgtechlabs/clean-workflow) is the broader +bundle for development, review, and Git/delivery guidance. Use this standalone +plugin when you only want Clean Commit. The new skill is maintained here; +adding its released versions to that bundle is separate downstream work. + +### Updates and development installation + +To refresh a Git marketplace and reinstall its plugin: + +```sh +codex plugin marketplace upgrade clean-commit +codex plugin remove clean-commit@clean-commit +codex plugin add clean-commit@clean-commit +``` + +Start a new chat after updating. The plugin version in +`.codex-plugin/plugin.json` versions the installable package separately from +the convention's specification version. Maintainers should bump the package +version when releasing skill changes; this addition does not publish a release +or add automated release infrastructure. + +Before a change reaches the default branch, test its feature branch with: + +```sh +codex plugin marketplace add wgtechlabs/clean-commit --ref BRANCH_OR_TAG +codex plugin add clean-commit@clean-commit +``` + +For local development, replace the marketplace source with the absolute path +to this checkout. Replace `BRANCH_OR_TAG` with the ref to test. Remove an existing +same-named marketplace before switching sources. See +[skill verification](tests/skill-scenarios.md) for installation checks and +representative behavior scenarios. + +### Skill ownership + +This repository is the canonical source for `clean-commit`. Maintain its skill +alongside [SPECIFICATION.md](SPECIFICATION.md), which remains authoritative. +Keep instructions self-contained and check examples against the specification. +Downstream bundles should import a released skill directory and record its +version and source commit, rather than maintain independent edits. A bundle +can lag until its update is reviewed and merged. + +--- + ## Why Clean Commit? Existing commit workflows are **too complex**. They require memorizing lengthy type names, complex scoping rules, and rigid formats that slow you down. diff --git a/skills/clean-commit/SKILL.md b/skills/clean-commit/SKILL.md new file mode 100644 index 0000000..aaae55e --- /dev/null +++ b/skills/clean-commit/SKILL.md @@ -0,0 +1,108 @@ +--- +name: clean-commit +description: Draft, validate, or create Clean Commit messages from Git changes when the repository adopts Clean Commit or the user requests it. Preserve other repositories' required commit conventions and distinguish drafting from committing. +--- + +# Clean Commit + +Write one clear message for one logical change. This skill works without +Clean Workflow or any other skill. Git is needed to inspect or commit local +changes; validating supplied message text alone needs no repository access. + +## Establish the convention and input + +Read repository instructions and contribution rules, then inspect recent +commits when a repository is available. Apply Clean Commit for an adopting +project or an explicit request, subject to repository requirements. Installing +the skill alone does not override an upstream project's commit convention. +If the user requests a Clean Commit example for comparison, keep it separate +from a commit that must follow another project's rules. + +For staged changes, inspect `git status --short`, `git diff --cached --stat`, +and the actual `git diff --cached`, including relevant callers or surrounding +code when needed to understand the change. Distinguish unstaged and untracked +work from the staged diff; do not describe them as part of the commit. If the +index is empty, say so rather than invent a staged change or stage files. +For a supplied diff or message, use that input and disclose missing context. + +## Subject format + +```text + : + (): + !: + ! (): +``` + +| Emoji | Type | Use | +| --- | --- | --- | +| ๐Ÿ“ฆ | `new` | New features, capabilities, or dependencies | +| ๐Ÿ”ง | `update` | Existing-code changes, refactoring, performance, ordinary bug fixes | +| ๐Ÿ—‘๏ธ | `remove` | Remove code, features, or dependencies | +| ๐Ÿ”’ | `security` | Security fixes and vulnerability remediation | +| โš™๏ธ | `setup` | Initial configuration, CI, build systems, or tooling | +| โ˜• | `chore` | Maintenance, dependency updates, or housekeeping | +| ๐Ÿงช | `test` | Test additions and test fixes | +| ๐Ÿ“– | `docs` | Documentation, guides, or comments | +| ๐Ÿš€ | `release` | Version releases or release preparation | + +Use the exact emoji and lowercase type. Prefer the specific purpose of the +change: adding a test is `test`, not `new`; a security fix is `security`, not +an ordinary `update`; new configuration is `setup`; ongoing dependency +maintenance is `chore`. Do not introduce a `fix` or `feat` type. + +The description starts lowercase, uses present tense, has no final period, +and accurately describes the diff. The **entire subject**, including emoji, +type, optional scope, spaces, and punctuation, must be at most 72 characters. +Count the complete subject instead of estimating from the description alone. + +Use one space between emoji and type, before an optional scope, and after the +colon. A scope is lowercase, preferably one word, and hyphenated when useful. +Omit it when it adds no clarity. Use one primary type; if the staged work is +unrelated, recommend splitting it without modifying the index unless asked. + +## Breaking changes + +Put a single `!` immediately after `new`, `update`, `remove`, or `security`, +before the optional scope or colon. It is invalid on `setup`, `chore`, `test`, +`docs`, or `release`. Choose the type from the actual change, then add `!` +only for a demonstrated compatibility break. Do not infer a break from size. + +Prefer a `BREAKING CHANGE:` body explaining the incompatibility and migration +when using `!`. The specification also accepts a subject marker alone and a +body-only `BREAKING CHANGE:` for backward compatibility; do not reject those +forms or invent missing migration details. + +```text +๐Ÿ”ง update! (api): return paginated results + +BREAKING CHANGE: callers must read items from the results field. +``` + +## Draft, validate, or commit + +- **Draft:** Return a usable message based on the requested diff. Briefly flag + mixed changes or unknowns that materially affect it. Do not stage, commit, + amend, or push during a draft-only request. +- **Validate:** Check format, exact emoji/type pairing, scope spacing, breaking + marker eligibility, length, tense, punctuation, and fit to the supplied + change. Explain concrete violations and give a corrected message when the + evidence permits. Format validity alone does not prove semantic accuracy. +- **Commit:** When committing is authorized, recheck the index and selected + files immediately before committing. Preserve unrelated work, follow + repository-required checks, and pass the message as literal data. For a + multiline body, use a message file rather than shell interpolation. Inspect + the resulting commit and remaining status afterward. Amend, history rewrite, + push, and release operations require their own scope in the user's request. + +Reuse authorization already given; do not add a confirmation step to an +already-authorized ordinary commit. Never bypass a failed required check or +claim a commit succeeded without verifying it. + +## Source and maintenance + +Derived from [Clean Commit specification v1.1.0](https://github.com/wgtechlabs/clean-commit/blob/main/SPECIFICATION.md). +The mandatory format rules govern over inconsistent illustrative examples. +The essential rules are bundled here for independent installed use. This +repository owns the skill; update it alongside specification changes. Clean +Workflow can consume released copies downstream. diff --git a/tests/skill-scenarios.md b/tests/skill-scenarios.md new file mode 100644 index 0000000..14c52ff --- /dev/null +++ b/tests/skill-scenarios.md @@ -0,0 +1,82 @@ +# Clean Commit skill verification + +These are repeatable manual checks, not a claim that an agent evaluation has +passed. Run them before releasing skill changes and record actual outcomes. +Use disposable local repositories with no push destination. + +## Installation + +1. In a test Codex environment without Clean Workflow, add this checkout as a + local marketplace: `codex plugin marketplace add /absolute/path/to/clean-commit`. +2. Run `codex plugin add clean-commit@clean-commit`, then + `codex plugin list --marketplace clean-commit --json`. Confirm installation. +3. Start a fresh chat and ask `$clean-commit validate this message: ๐Ÿ“ฆ new: add search`. + Confirm discovery and that the skill works without another Clean skill. +4. Load only `skills/clean-commit/` in another Agent Skills-compatible host and + repeat the request. No resource outside that folder should be required. +5. For remote installation, repeat with `wgtechlabs/clean-commit --ref BRANCH_OR_TAG` + as the marketplace source. Verify the installed source matches the tested ref. +6. Remove only the test installation and marketplace afterward. + +## Behavior + +Record prompts, initial index/status/HEAD, responses, and final index/status/HEAD. +Drafting and validation must leave all three unchanged. + +| Request or setup | Expected observable result | +| --- | --- | +| Draft from a staged ordinary bug fix and unstaged new feature | Message describes only the fix using `๐Ÿ”ง update`; the unstaged feature is excluded | +| Draft from an empty index | Reports no staged changes; does not stage files or fabricate a commit | +| Draft from unrelated staged feature and docs edits | Recommends splitting logical changes without changing the index | +| Validate `๐Ÿ“ฆ new: add search` and `๐Ÿ”ง update (api): fix pagination` | Accepts both format forms | +| Validate `๐Ÿ“ฆ new(api): add search` and `๐Ÿ”ง update: Fix pagination.` | Identifies scope spacing, capitalization, and final-period violations | +| Validate `๐Ÿ”ง update! (api): change response shape` and `โš™๏ธ setup!: add ci` | Accepts the eligible breaking marker and rejects `!` on setup | +| Validate a body-only `BREAKING CHANGE:` or eligible subject-only `!` | Recognizes both supported forms; recommends body detail without inventing it | +| Validate complete subjects of exactly 72 and 73 characters | Accepts the length of the first and rejects the second, counting prefix and scope too | +| Repo requires Conventional Commits; draft for its staged change | Follows the repository rule without migrating its convention | +| Commit a specifically staged change with commit authorization | Rechecks the index, runs required checks, commits only intended work, and verifies the resulting commit; no push or amend | + +Exercise all nine type choices with matching changes: new capability (`new`), +ordinary fix (`update`), feature deletion (`remove`), vulnerability fix +(`security`), initial CI configuration (`setup`), dependency update (`chore`), +test-only change (`test`), guide-only change (`docs`), and release preparation +(`release`). Check exact emoji/type pairing against `SPECIFICATION.md`. + +To produce deterministic length inputs, run: + +```sh +python3 - <<'PY' +prefix = '๐Ÿ“– docs: ' +for length in (72, 73): + subject = prefix + 'a' * (length - len(prefix)) + print(length, subject) +PY +``` + +Package discovery and static inspection do not prove these behavioral checks. + +## Recorded installation check (2026-09-30) + +Passed with Codex CLI `0.158.0-alpha.2.1` and this PR's local checkout: + +1. Created an empty temporary Codex data directory and an empty workspace + outside the checkout. Configured only the test child processes to use that + data directory; no user configuration, plugins, or credentials were copied. +2. Added this checkout as a local marketplace and installed `clean-commit@clean-commit`. + `codex plugin list --marketplace clean-commit --json` reported version + `0.1.0` installed and enabled. +3. Started a new `codex app-server --stdio`, initialized its protocol, and + called `skills/list` with the empty workspace and `forceReload: true`. + `clean-commit:clean-commit` was enabled, loaded from the temporary plugin + cache, and its file bytes matched `skills/clean-commit/SKILL.md` exactly. +4. Checked the complete discovery result: this was the only Clean skill; + Clean Workflow was absent from both discovery and the temporary data + directory. Created a fresh ephemeral session with `thread/start` successfully. +5. Removed the test plugin and marketplace and discarded the temporary data + directory. The user's installed plugins and configuration were unchanged. + +This verifies standalone installation and fresh-session discovery without +Clean Workflow. The operating-system user home was not isolated: unrelated +TRM Agent Skills and Codex built-in skills remained discoverable. No model +turn, other vendor's host, or live GitHub mutation was exercised by this check. +The behavior scenarios above remain separate checks. From 6a0f59e9097e6c6fccc2eee0f42a637d65245882 Mon Sep 17 00:00:00 2001 From: Waren Gonzaga Date: Wed, 30 Sep 2026 12:11:26 +0800 Subject: [PATCH 2/3] =?UTF-8?q?=F0=9F=93=96=20docs:=20expand=20standalone?= =?UTF-8?q?=20skill=20setup=20and=20usage=20guide?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- README.md | 91 +++++++++++++++++++++++++++++++++++++------------------ 1 file changed, 61 insertions(+), 30 deletions(-) diff --git a/README.md b/README.md index 60dcfad..5c94e87 100644 --- a/README.md +++ b/README.md @@ -15,35 +15,58 @@ A minimalist git commit workflow designed to be simple, memorable, and universal ## Install the agent skill -Use **Clean Commit** on its own, like the standalone -[Clean Coding](https://github.com/wgtechlabs/clean-coding) and -[Clean Code Review](https://github.com/wgtechlabs/clean-code-review) plugins: +Install **Clean Commit** as a standalone skill for AI assistants. It includes its +own instructions and works without Clean Workflow or another Clean skill. +You can also use the convention manually with the guides below. + +### Requirements + +Use a Codex version with `codex plugin` support; installation and discovery +were verified with Codex CLI `0.158.0-alpha.2.1`. +Git and a local repository are required to inspect changes or create commits. Message-only validation does not need GitHub access. + +### Install in Codex + +Install the stable version from `main`: ```sh -codex plugin marketplace add wgtechlabs/clean-commit +codex plugin marketplace add wgtechlabs/clean-commit --ref main codex plugin add clean-commit@clean-commit +codex plugin list --marketplace clean-commit --json ``` -Start a new chat and invoke `$clean-commit`, for example: +Confirm the plugin is installed and enabled, then start a new chat and invoke +`$clean-commit`. Installation alone does not authorize repository changes. + +### Example requests ```text $clean-commit draft a message for my staged changes without committing + +$clean-commit validate this message: ๐Ÿ”ง update (api): fix pagination + +$clean-commit check whether my staged changes should be split into separate commits ``` -For another Agent Skills-compatible host, load the entire -[`skills/clean-commit/`](skills/clean-commit/SKILL.md) folder using that host's skill -installation mechanism. All essential instructions are included; no other -Clean skill is required. The host still needs the tools and access used by the -requested operation. Installation does not authorize repository changes. +Drafts describe the staged diff. Drafting and validation do not stage files, +create commits, amend history, or push. The target repository's explicit +commit convention takes precedence. + +### Other Agent Skills hosts -[Clean Workflow](https://github.com/wgtechlabs/clean-workflow) is the broader -bundle for development, review, and Git/delivery guidance. Use this standalone -plugin when you only want Clean Commit. The new skill is maintained here; -adding its released versions to that bundle is separate downstream work. +Load the entire [`skills/clean-commit/`](skills/clean-commit/SKILL.md) folder using +your host's skill installation mechanism. The instructions are self-contained; +the host must still provide the tools required for the requested operation. +Other vendors' hosts have not been verified in this repository's test record. -### Updates and development installation +[Clean Workflow](https://github.com/wgtechlabs/clean-workflow) provides broader +development, review, and delivery guidance. Choose this standalone plugin for +Clean Commit alone. This repository owns the skill; updates to the broader bundle +are maintained separately. -To refresh a Git marketplace and reinstall its plugin: +### Update or remove + +Refresh the configured marketplace and reinstall its plugin: ```sh codex plugin marketplace upgrade clean-commit @@ -51,24 +74,32 @@ codex plugin remove clean-commit@clean-commit codex plugin add clean-commit@clean-commit ``` -Start a new chat after updating. The plugin version in -`.codex-plugin/plugin.json` versions the installable package separately from -the convention's specification version. Maintainers should bump the package -version when releasing skill changes; this addition does not publish a release -or add automated release infrastructure. +Start a new chat after updating. To uninstall and remove its marketplace: -Before a change reaches the default branch, test its feature branch with: +```sh +codex plugin remove clean-commit@clean-commit +codex plugin marketplace remove clean-commit +``` + +### Preview development changes + +To test `dev` before promotion to `main`, first remove an existing installation +and same-named marketplace with the commands above, then run: ```sh -codex plugin marketplace add wgtechlabs/clean-commit --ref BRANCH_OR_TAG +codex plugin marketplace add wgtechlabs/clean-commit --ref dev codex plugin add clean-commit@clean-commit ``` -For local development, replace the marketplace source with the absolute path -to this checkout. Replace `BRANCH_OR_TAG` with the ref to test. Remove an existing -same-named marketplace before switching sources. See -[skill verification](tests/skill-scenarios.md) for installation checks and -representative behavior scenarios. +Use another branch or an existing tag instead of `dev` to test a specific ref. +For local development, use the absolute checkout path as the marketplace source +and omit `--ref`. Switch back to the stable installation commands after testing. +See [skill verification](tests/skill-scenarios.md) for recorded installation +results, behavior scenarios, and verification limits. + +The installable package is version `0.1.0`, tracked in +[`.codex-plugin/plugin.json`](.codex-plugin/plugin.json). The version badge at +the top of this README refers to the convention specification, not the plugin. ### Skill ownership @@ -146,10 +177,10 @@ Clean Commit is different: ### Rules - Use lowercase for type -- Use `!` immediately after type (no space) to signal a breaking change +- Use `!` immediately after type (no space) for breaking changes on `new`, `update`, `remove`, or `security` - Use present tense ("add" not "added") - No period at the end -- Keep description under 72 characters +- Keep the complete subject at most 72 characters, including emoji, type, scope, and description --- From 3b06934daabfdfea40cb03b7b44fbc2c0eb3ebd3 Mon Sep 17 00:00:00 2001 From: Waren Gonzaga Date: Wed, 30 Sep 2026 17:58:40 +0800 Subject: [PATCH 3/3] =?UTF-8?q?=E2=9A=99=EF=B8=8F=20setup:=20add=20release?= =?UTF-8?q?=20build=20flow=20automation?= MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit --- .github/workflows/release.yml | 52 +++++++++++++++++++++++++++++++++++ README.md | 13 ++++++++- 2 files changed, 64 insertions(+), 1 deletion(-) create mode 100644 .github/workflows/release.yml diff --git a/.github/workflows/release.yml b/.github/workflows/release.yml new file mode 100644 index 0000000..62ff2f2 --- /dev/null +++ b/.github/workflows/release.yml @@ -0,0 +1,52 @@ +name: Release + +on: + push: + branches: [main] + +permissions: + contents: write + +concurrency: + group: release + cancel-in-progress: false + +jobs: + release: + runs-on: ubuntu-latest + steps: + - uses: actions/checkout@v4 + with: + ref: main + fetch-depth: 0 + + - name: Plan release + id: plan + uses: wgtechlabs/release-build-flow-action@6df9cb42c24c296d902150d051a0b6be4422cccc # v1 + with: + initial-version: 0.1.0 + dry-run: true + changelog-enabled: false + sync-version-files: false + + - name: Update plugin version + if: steps.plan.outputs.version-bump-type != 'none' + env: + RELEASE_VERSION: ${{ steps.plan.outputs.version }} + run: | + jq --arg version "$RELEASE_VERSION" '.version = $version' .codex-plugin/plugin.json > "$RUNNER_TEMP/plugin.json" + mv "$RUNNER_TEMP/plugin.json" .codex-plugin/plugin.json + git add .codex-plugin/plugin.json + + - name: Publish release + if: steps.plan.outputs.version-bump-type != 'none' + uses: wgtechlabs/release-build-flow-action@6df9cb42c24c296d902150d051a0b6be4422cccc # v1 + with: + planned-version: ${{ steps.plan.outputs.version }} + planned-version-tag: ${{ steps.plan.outputs.version-tag }} + planned-version-bump-type: ${{ steps.plan.outputs.version-bump-type }} + planned-previous-version: ${{ steps.plan.outputs.previous-version }} + sync-version-files: false + changelog-path: ./CHANGELOG.md + commit-changelog: true + create-release: true diff --git a/README.md b/README.md index 5c94e87..8d05573 100644 --- a/README.md +++ b/README.md @@ -97,10 +97,21 @@ and omit `--ref`. Switch back to the stable installation commands after testing. See [skill verification](tests/skill-scenarios.md) for recorded installation results, behavior scenarios, and verification limits. -The installable package is version `0.1.0`, tracked in +The current installable package version is tracked in [`.codex-plugin/plugin.json`](.codex-plugin/plugin.json). The version badge at the top of this README refers to the convention specification, not the plugin. +### Automated releases + +Pushes to `main`, including a merged promotion PR, run the +[release workflow](.github/workflows/release.yml). It uses the same pinned +[Release Build Flow Action](https://github.com/wgtechlabs/release-build-flow-action) +configuration as Clean Coding and Clean Code Review: plan the version, update +the plugin manifest, then commit `CHANGELOG.md` and publish a tag and GitHub +Release when a version bump is needed. Existing release tags determine the +next version; `0.1.0` is the initial version when no tags exist. Other package +manifests are not synchronized by this workflow. + ### Skill ownership This repository is the canonical source for `clean-commit`. Maintain its skill