Commit Discipline#

Use this skill at the moment you are about to git add, git commit, or gh pr create. It encodes how this repo expects commits and PRs to look so that history stays readable and release tooling (release-please, changelogs) keeps working.

When to use this skill#

Load it when you are about to:

• Stage changes for commit.
• Author a commit message.
• Rebase onto origin/main before opening a PR.
• Open or update a pull request.

Skip it for purely exploratory commands that do not touch git state.

Conventional Commits#

This repo uses Conventional Commits. The release tooling (release-please-config.json) reads commit subjects to decide version bumps and changelog entries. Format:

<type>(<optional-scope>): <imperative summary>

Allowed type values:

• feat — user-visible new functionality.
• fix — user-visible bug fix.
• perf — performance improvement with no behavior change.
• refactor — internal restructuring, no behavior change, no new feature.
• docs — documentation only.
• test — tests only.
• build — build system, packaging, dependencies.
• ci — CI configuration only.
• chore — repo plumbing that does not fit the above and has no user impact.
• revert — reverts a previous commit; reference the reverted SHA.

Rules:

• Subject in the imperative mood, no trailing period, max 72 chars.
• Use a scope when the change is localized (e.g., feat(cli): ..., fix(parser): ..., feat(remote-registry): ...).
• Use ! for breaking changes (e.g., feat(cli)!: rename --token to --auth-token) AND include a BREAKING CHANGE: footer explaining the migration.
• Body (optional) explains why, not what; reference issues/PRs by number.

Commit hygiene#

• One logical change per commit. Do not bundle unrelated edits.
• Never commit secrets, .env* files, real tokens, generated dist/ output (unless explicitly requested), node_modules/, or local Supabase data.
• Never amend or force-push commits that already exist on main. Force-push to feature branches is allowed only with --force-with-lease.
• If pre-commit / pre-push hooks fail, fix the underlying issue. Do not bypass with --no-verify unless the user explicitly asks.

Before opening a PR#

Inside the feature worktree:

git fetch origin
git rebase origin/main
bun run lint
bun test
bun run build

Plus the conditional scripts from repo-hygiene / doc-sync when applicable.

If the rebase produces conflicts you cannot confidently resolve, stop and surface them to the user instead of force-pushing through them.

PR description template#

Open PRs against main with a description that contains:

1. Summary — 1–3 bullets describing the change in user-visible terms.
2. Why — link to the issue, spec, or user request driving the change.
3. How — short note on the approach; call out anything non-obvious.
4. Validation — list the exact commands you ran and that they passed (lint, test, build, plus any conditional ones).
5. Docs — link to the doc files updated, or state explicitly "no user-visible behavior changed".
6. Risk / rollout — call out feature flags, migration steps, or follow-ups.

Example title:

feat(cli): add `wfm pull --output` flag for redirecting fetched workflows

Anti-patterns to refuse#

• Subjects like update stuff, wip, fix things, address review.
• Squashing unrelated commits together to "clean up history" right before merge.
• Pushing to main directly.
• Opening a PR with failing CI and asking reviewers to "ignore the red".
• Mixing a refactor and a behavior change in the same commit.

Definition of done#

• Every commit subject is a valid Conventional Commit.
• Branch is rebased on the latest origin/main.
• All required scripts (lint, test, build, plus conditional ones) passed locally.
• PR description follows the template and links updated docs.