Skip to content

Commit fba4c29

Browse files
warengonzagawarengonzaga
authored
Merge pull request #14 from wgtechlabs/dev
🚀 release: promote standalone clean-commit skill
2 parents 9de32a3 + 3b06934 commit fba4c29

6 files changed

Lines changed: 406 additions & 2 deletions

File tree

‎.agents/plugins/marketplace.json‎

Lines changed: 20 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,20 @@
1+
{
2+
"name": "clean-commit",
3+
"interface": {
4+
"displayName": "Clean Commit"
5+
},
6+
"plugins": [
7+
{
8+
"name": "clean-commit",
9+
"source": {
10+
"source": "local",
11+
"path": "./"
12+
},
13+
"policy": {
14+
"installation": "AVAILABLE",
15+
"authentication": "ON_INSTALL"
16+
},
17+
"category": "Productivity"
18+
}
19+
]
20+
}

‎.codex-plugin/plugin.json‎

Lines changed: 32 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,32 @@
1+
{
2+
"name": "clean-commit",
3+
"version": "0.1.0",
4+
"description": "Draft, validate, and create commit messages from the actual Git changes.",
5+
"author": {
6+
"name": "WG Technology Labs",
7+
"url": "https://github.com/wgtechlabs"
8+
},
9+
"homepage": "https://github.com/wgtechlabs/clean-commit",
10+
"repository": "https://github.com/wgtechlabs/clean-commit",
11+
"license": "MIT",
12+
"keywords": [
13+
"commits",
14+
"workflow",
15+
"skills"
16+
],
17+
"skills": "./skills/",
18+
"interface": {
19+
"displayName": "Clean Commit",
20+
"shortDescription": "Write and validate Clean Commit messages",
21+
"longDescription": "Draft, validate, and create commit messages from the actual Git changes.",
22+
"developerName": "WG Technology Labs",
23+
"category": "Productivity",
24+
"capabilities": [
25+
"Instructions"
26+
],
27+
"websiteURL": "https://github.com/wgtechlabs/clean-commit",
28+
"defaultPrompt": [
29+
"Use $clean-commit to draft a message for my staged changes without committing."
30+
]
31+
}
32+
}

‎.github/workflows/release.yml‎

Lines changed: 52 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,52 @@
1+
name: Release
2+
3+
on:
4+
push:
5+
branches: [main]
6+
7+
permissions:
8+
contents: write
9+
10+
concurrency:
11+
group: release
12+
cancel-in-progress: false
13+
14+
jobs:
15+
release:
16+
runs-on: ubuntu-latest
17+
steps:
18+
- uses: actions/checkout@v4
19+
with:
20+
ref: main
21+
fetch-depth: 0
22+
23+
- name: Plan release
24+
id: plan
25+
uses: wgtechlabs/release-build-flow-action@6df9cb42c24c296d902150d051a0b6be4422cccc # v1
26+
with:
27+
initial-version: 0.1.0
28+
dry-run: true
29+
changelog-enabled: false
30+
sync-version-files: false
31+
32+
- name: Update plugin version
33+
if: steps.plan.outputs.version-bump-type != 'none'
34+
env:
35+
RELEASE_VERSION: ${{ steps.plan.outputs.version }}
36+
run: |
37+
jq --arg version "$RELEASE_VERSION" '.version = $version' .codex-plugin/plugin.json > "$RUNNER_TEMP/plugin.json"
38+
mv "$RUNNER_TEMP/plugin.json" .codex-plugin/plugin.json
39+
git add .codex-plugin/plugin.json
40+
41+
- name: Publish release
42+
if: steps.plan.outputs.version-bump-type != 'none'
43+
uses: wgtechlabs/release-build-flow-action@6df9cb42c24c296d902150d051a0b6be4422cccc # v1
44+
with:
45+
planned-version: ${{ steps.plan.outputs.version }}
46+
planned-version-tag: ${{ steps.plan.outputs.version-tag }}
47+
planned-version-bump-type: ${{ steps.plan.outputs.version-bump-type }}
48+
planned-previous-version: ${{ steps.plan.outputs.previous-version }}
49+
sync-version-files: false
50+
changelog-path: ./CHANGELOG.md
51+
commit-changelog: true
52+
create-release: true

‎README.md‎

Lines changed: 112 additions & 2 deletions
Original file line numberDiff line numberDiff line change
@@ -13,6 +13,116 @@ A minimalist git commit workflow designed to be simple, memorable, and universal
1313

1414
---
1515

16+
## Install the agent skill
17+
18+
Install **Clean Commit** as a standalone skill for AI assistants. It includes its
19+
own instructions and works without Clean Workflow or another Clean skill.
20+
You can also use the convention manually with the guides below.
21+
22+
### Requirements
23+
24+
Use a Codex version with `codex plugin` support; installation and discovery
25+
were verified with Codex CLI `0.158.0-alpha.2.1`.
26+
Git and a local repository are required to inspect changes or create commits. Message-only validation does not need GitHub access.
27+
28+
### Install in Codex
29+
30+
Install the stable version from `main`:
31+
32+
```sh
33+
codex plugin marketplace add wgtechlabs/clean-commit --ref main
34+
codex plugin add clean-commit@clean-commit
35+
codex plugin list --marketplace clean-commit --json
36+
```
37+
38+
Confirm the plugin is installed and enabled, then start a new chat and invoke
39+
`$clean-commit`. Installation alone does not authorize repository changes.
40+
41+
### Example requests
42+
43+
```text
44+
$clean-commit draft a message for my staged changes without committing
45+
46+
$clean-commit validate this message: 🔧 update (api): fix pagination
47+
48+
$clean-commit check whether my staged changes should be split into separate commits
49+
```
50+
51+
Drafts describe the staged diff. Drafting and validation do not stage files,
52+
create commits, amend history, or push. The target repository's explicit
53+
commit convention takes precedence.
54+
55+
### Other Agent Skills hosts
56+
57+
Load the entire [`skills/clean-commit/`](skills/clean-commit/SKILL.md) folder using
58+
your host's skill installation mechanism. The instructions are self-contained;
59+
the host must still provide the tools required for the requested operation.
60+
Other vendors' hosts have not been verified in this repository's test record.
61+
62+
[Clean Workflow](https://github.com/wgtechlabs/clean-workflow) provides broader
63+
development, review, and delivery guidance. Choose this standalone plugin for
64+
Clean Commit alone. This repository owns the skill; updates to the broader bundle
65+
are maintained separately.
66+
67+
### Update or remove
68+
69+
Refresh the configured marketplace and reinstall its plugin:
70+
71+
```sh
72+
codex plugin marketplace upgrade clean-commit
73+
codex plugin remove clean-commit@clean-commit
74+
codex plugin add clean-commit@clean-commit
75+
```
76+
77+
Start a new chat after updating. To uninstall and remove its marketplace:
78+
79+
```sh
80+
codex plugin remove clean-commit@clean-commit
81+
codex plugin marketplace remove clean-commit
82+
```
83+
84+
### Preview development changes
85+
86+
To test `dev` before promotion to `main`, first remove an existing installation
87+
and same-named marketplace with the commands above, then run:
88+
89+
```sh
90+
codex plugin marketplace add wgtechlabs/clean-commit --ref dev
91+
codex plugin add clean-commit@clean-commit
92+
```
93+
94+
Use another branch or an existing tag instead of `dev` to test a specific ref.
95+
For local development, use the absolute checkout path as the marketplace source
96+
and omit `--ref`. Switch back to the stable installation commands after testing.
97+
See [skill verification](tests/skill-scenarios.md) for recorded installation
98+
results, behavior scenarios, and verification limits.
99+
100+
The current installable package version is tracked in
101+
[`.codex-plugin/plugin.json`](.codex-plugin/plugin.json). The version badge at
102+
the top of this README refers to the convention specification, not the plugin.
103+
104+
### Automated releases
105+
106+
Pushes to `main`, including a merged promotion PR, run the
107+
[release workflow](.github/workflows/release.yml). It uses the same pinned
108+
[Release Build Flow Action](https://github.com/wgtechlabs/release-build-flow-action)
109+
configuration as Clean Coding and Clean Code Review: plan the version, update
110+
the plugin manifest, then commit `CHANGELOG.md` and publish a tag and GitHub
111+
Release when a version bump is needed. Existing release tags determine the
112+
next version; `0.1.0` is the initial version when no tags exist. Other package
113+
manifests are not synchronized by this workflow.
114+
115+
### Skill ownership
116+
117+
This repository is the canonical source for `clean-commit`. Maintain its skill
118+
alongside [SPECIFICATION.md](SPECIFICATION.md), which remains authoritative.
119+
Keep instructions self-contained and check examples against the specification.
120+
Downstream bundles should import a released skill directory and record its
121+
version and source commit, rather than maintain independent edits. A bundle
122+
can lag until its update is reviewed and merged.
123+
124+
---
125+
16126
## Why Clean Commit?
17127

18128
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:
78188

79189
### Rules
80190
- Use lowercase for type
81-
- Use `!` immediately after type (no space) to signal a breaking change
191+
- Use `!` immediately after type (no space) for breaking changes on `new`, `update`, `remove`, or `security`
82192
- Use present tense ("add" not "added")
83193
- No period at the end
84-
- Keep description under 72 characters
194+
- Keep the complete subject at most 72 characters, including emoji, type, scope, and description
85195

86196
---
87197

‎skills/clean-commit/SKILL.md‎

Lines changed: 108 additions & 0 deletions
Original file line numberDiff line numberDiff line change
@@ -0,0 +1,108 @@
1+
---
2+
name: clean-commit
3+
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.
4+
---
5+
6+
# Clean Commit
7+
8+
Write one clear message for one logical change. This skill works without
9+
Clean Workflow or any other skill. Git is needed to inspect or commit local
10+
changes; validating supplied message text alone needs no repository access.
11+
12+
## Establish the convention and input
13+
14+
Read repository instructions and contribution rules, then inspect recent
15+
commits when a repository is available. Apply Clean Commit for an adopting
16+
project or an explicit request, subject to repository requirements. Installing
17+
the skill alone does not override an upstream project's commit convention.
18+
If the user requests a Clean Commit example for comparison, keep it separate
19+
from a commit that must follow another project's rules.
20+
21+
For staged changes, inspect `git status --short`, `git diff --cached --stat`,
22+
and the actual `git diff --cached`, including relevant callers or surrounding
23+
code when needed to understand the change. Distinguish unstaged and untracked
24+
work from the staged diff; do not describe them as part of the commit. If the
25+
index is empty, say so rather than invent a staged change or stage files.
26+
For a supplied diff or message, use that input and disclose missing context.
27+
28+
## Subject format
29+
30+
```text
31+
<emoji> <type>: <description>
32+
<emoji> <type> (<scope>): <description>
33+
<emoji> <type>!: <description>
34+
<emoji> <type>! (<scope>): <description>
35+
```
36+
37+
| Emoji | Type | Use |
38+
| --- | --- | --- |
39+
| 📦 | `new` | New features, capabilities, or dependencies |
40+
| 🔧 | `update` | Existing-code changes, refactoring, performance, ordinary bug fixes |
41+
| 🗑️ | `remove` | Remove code, features, or dependencies |
42+
| 🔒 | `security` | Security fixes and vulnerability remediation |
43+
| ⚙️ | `setup` | Initial configuration, CI, build systems, or tooling |
44+
| ☕ | `chore` | Maintenance, dependency updates, or housekeeping |
45+
| 🧪 | `test` | Test additions and test fixes |
46+
| 📖 | `docs` | Documentation, guides, or comments |
47+
| 🚀 | `release` | Version releases or release preparation |
48+
49+
Use the exact emoji and lowercase type. Prefer the specific purpose of the
50+
change: adding a test is `test`, not `new`; a security fix is `security`, not
51+
an ordinary `update`; new configuration is `setup`; ongoing dependency
52+
maintenance is `chore`. Do not introduce a `fix` or `feat` type.
53+
54+
The description starts lowercase, uses present tense, has no final period,
55+
and accurately describes the diff. The **entire subject**, including emoji,
56+
type, optional scope, spaces, and punctuation, must be at most 72 characters.
57+
Count the complete subject instead of estimating from the description alone.
58+
59+
Use one space between emoji and type, before an optional scope, and after the
60+
colon. A scope is lowercase, preferably one word, and hyphenated when useful.
61+
Omit it when it adds no clarity. Use one primary type; if the staged work is
62+
unrelated, recommend splitting it without modifying the index unless asked.
63+
64+
## Breaking changes
65+
66+
Put a single `!` immediately after `new`, `update`, `remove`, or `security`,
67+
before the optional scope or colon. It is invalid on `setup`, `chore`, `test`,
68+
`docs`, or `release`. Choose the type from the actual change, then add `!`
69+
only for a demonstrated compatibility break. Do not infer a break from size.
70+
71+
Prefer a `BREAKING CHANGE:` body explaining the incompatibility and migration
72+
when using `!`. The specification also accepts a subject marker alone and a
73+
body-only `BREAKING CHANGE:` for backward compatibility; do not reject those
74+
forms or invent missing migration details.
75+
76+
```text
77+
🔧 update! (api): return paginated results
78+
79+
BREAKING CHANGE: callers must read items from the results field.
80+
```
81+
82+
## Draft, validate, or commit
83+
84+
- **Draft:** Return a usable message based on the requested diff. Briefly flag
85+
mixed changes or unknowns that materially affect it. Do not stage, commit,
86+
amend, or push during a draft-only request.
87+
- **Validate:** Check format, exact emoji/type pairing, scope spacing, breaking
88+
marker eligibility, length, tense, punctuation, and fit to the supplied
89+
change. Explain concrete violations and give a corrected message when the
90+
evidence permits. Format validity alone does not prove semantic accuracy.
91+
- **Commit:** When committing is authorized, recheck the index and selected
92+
files immediately before committing. Preserve unrelated work, follow
93+
repository-required checks, and pass the message as literal data. For a
94+
multiline body, use a message file rather than shell interpolation. Inspect
95+
the resulting commit and remaining status afterward. Amend, history rewrite,
96+
push, and release operations require their own scope in the user's request.
97+
98+
Reuse authorization already given; do not add a confirmation step to an
99+
already-authorized ordinary commit. Never bypass a failed required check or
100+
claim a commit succeeded without verifying it.
101+
102+
## Source and maintenance
103+
104+
Derived from [Clean Commit specification v1.1.0](https://github.com/wgtechlabs/clean-commit/blob/main/SPECIFICATION.md).
105+
The mandatory format rules govern over inconsistent illustrative examples.
106+
The essential rules are bundled here for independent installed use. This
107+
repository owns the skill; update it alongside specification changes. Clean
108+
Workflow can consume released copies downstream.

0 commit comments

Comments
 (0)