🚀 release: promote standalone clean-commit skill

.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"
+    }
+  ]
+}

.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."
+    ]
+  }
+}

.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

README.md

@@ -13,6 +13,116 @@ A minimalist git commit workflow designed to be simple, memorable, and universal
 
 ---
 
+## Install the agent skill
+
+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 --ref main
+codex plugin add clean-commit@clean-commit
+codex plugin list --marketplace clean-commit --json
+```
+
+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
+```
+
+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
+
+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.
+
+[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.
+
+### Update or remove
+
+Refresh the configured 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. To uninstall and remove its marketplace:
+
+```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 dev
+codex plugin add clean-commit@clean-commit
+```
+
+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 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
+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.
@@ -78,10 +188,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
 
 ---
 

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>: <description>
+<emoji> <type> (<scope>): <description>
+<emoji> <type>!: <description>
+<emoji> <type>! (<scope>): <description>
+```
+
+| 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.