feat(git-plugin): add complete git workflow automation suite
## Why The git plugin only covered a partial slice of common git workflows. This adds the remaining skill set (branches, commits, history, remotes, submodules, workflow, worktrees) plus a git-orchestrate agent so the plugin can handle end-to-end git automation instead of a handful of commands. ## Implementation Notes Each new skill was validated against its research docs and org conventions after initial authoring, which surfaced hallucinated version pins, factual errors, and completeness gaps that were corrected in the same pass rather than left for follow-up. ## Impact Bumps the git plugin to 1.3.0. Co-authored-by: Claude Sonnet 5 <noreply@anthropic.com>
This commit is contained in:
66
plugins/git/skills/git-commits/references/commit-template.md
Normal file
66
plugins/git/skills/git-commits/references/commit-template.md
Normal file
@@ -0,0 +1,66 @@
|
||||
---
|
||||
source_keys:
|
||||
- org-commit-conventions
|
||||
---
|
||||
|
||||
# Commit Message Body Template
|
||||
|
||||
Use this structure for the body/footer of any non-trivial commit (skip sections that don't apply — do not leave placeholders in the actual commit).
|
||||
|
||||
```
|
||||
<type>(<scope>): <concise summary>
|
||||
```
|
||||
The header is required. Describe the intended outcome, not the implementation.
|
||||
|
||||
## Why
|
||||
|
||||
Explain why this change exists. This is the most valuable part of the commit — the diff already shows *what* changed; future maintainers (human or AI) need *why*.
|
||||
|
||||
Include, where applicable:
|
||||
- Problem being solved
|
||||
- User or business need
|
||||
- Bug or root cause
|
||||
- Important context not visible in the code
|
||||
|
||||
Omit if the reason is immediately obvious.
|
||||
|
||||
## Implementation Notes
|
||||
|
||||
Capture decisions that are difficult to infer from the code:
|
||||
- Why this approach was chosen
|
||||
- Important assumptions or invariants
|
||||
- Constraints imposed by external systems
|
||||
- Tradeoffs or intentional compromises
|
||||
- Non-obvious implementation details
|
||||
- Workarounds or temporary solutions
|
||||
|
||||
Do NOT describe the diff ("renamed X", "added Y"). Omit if there's nothing worth preserving.
|
||||
|
||||
## Impact
|
||||
|
||||
Document effects future developers should know about:
|
||||
- Behavior changes
|
||||
- Breaking changes
|
||||
- Performance implications
|
||||
- Security considerations
|
||||
- Migration or deployment requirements
|
||||
- Compatibility concerns
|
||||
- Follow-up work or known limitations
|
||||
|
||||
Omit if there are no noteworthy impacts.
|
||||
|
||||
## Trailers
|
||||
|
||||
Structured metadata for traceability and tooling. Use only the trailers that apply:
|
||||
|
||||
```
|
||||
Fixes:
|
||||
Refs:
|
||||
ADR:
|
||||
RFC:
|
||||
Design:
|
||||
Co-authored-by:
|
||||
Reviewed-by:
|
||||
Signed-off-by:
|
||||
BREAKING CHANGE:
|
||||
```
|
||||
@@ -0,0 +1,170 @@
|
||||
---
|
||||
source_keys:
|
||||
- conventional-commits-spec
|
||||
- commitlint-config-conventional
|
||||
---
|
||||
|
||||
# Conventional Commits Specification (v1.0.0)
|
||||
|
||||
Conventional Commits is a lightweight convention on top of commit messages that provides a set of rules for creating an explicit commit history. It enables automated tooling (CHANGELOG generation, semantic version bumping) and structured filtering.
|
||||
|
||||
## Message Format
|
||||
|
||||
```
|
||||
<type>[optional scope]: <description>
|
||||
|
||||
[optional body]
|
||||
|
||||
[optional footer(s)]
|
||||
```
|
||||
|
||||
Each section is separated by a blank line. The header is the only required part.
|
||||
|
||||
## Rules
|
||||
|
||||
| Element | Rule |
|
||||
|---|---|
|
||||
| `type` | Required. Lowercase noun. |
|
||||
| `scope` | Optional. Noun in parentheses directly after type: `feat(api):`. |
|
||||
| `description` | Required. Immediately follows `type/scope: `. Imperative mood, no trailing period. |
|
||||
| `body` | Optional. Begins one blank line after description. Free-form prose, multiple paragraphs allowed. Lines max 100 characters. |
|
||||
| `footer(s)` | Optional. Begins one blank line after body (or description). `<token>: <value>` format. Lines max 100 characters. |
|
||||
| `BREAKING CHANGE` | Must be uppercase. Either a footer token or signalled by `!` before the colon. |
|
||||
|
||||
## Standard Types
|
||||
|
||||
The spec itself mandates only `feat` and `fix`. The 11-type set below is the de-facto standard from `@commitlint/config-conventional` (Angular commit message guidelines), not a spec requirement — but it is what this skill validates against.
|
||||
|
||||
### 11-type set (commitlint/config-conventional)
|
||||
|
||||
| Type | Meaning | SemVer impact | Appears in CHANGELOG |
|
||||
|---|---|---|---|
|
||||
| `feat` | New user-visible feature | MINOR | Yes |
|
||||
| `fix` | Bug fix | PATCH | Yes |
|
||||
| `perf` | Performance improvement, no API change | PATCH | Yes |
|
||||
| `revert` | Reverts a previous commit | PATCH | Yes |
|
||||
| `docs` | Documentation only | none | No |
|
||||
| `style` | Formatting, whitespace — no logic change | none | No |
|
||||
| `refactor` | Code restructuring — no feature or fix | none | No |
|
||||
| `test` | Adding or fixing tests | none | No |
|
||||
| `build` | Build system or external dependency changes | none | No |
|
||||
| `ci` | CI configuration and scripts | none | No |
|
||||
| `chore` | Anything not fitting above | none | No |
|
||||
|
||||
A `BREAKING CHANGE` footer or `!` on **any** type always triggers a MAJOR bump.
|
||||
|
||||
## Breaking Changes
|
||||
|
||||
Two equivalent notations:
|
||||
|
||||
**`!` in header** (preferred — visible in `git log --oneline`):
|
||||
```
|
||||
feat!: drop support for Node 6
|
||||
feat(api)!: remove deprecated endpoint
|
||||
```
|
||||
|
||||
**`BREAKING CHANGE` footer** (machine-readable body):
|
||||
```
|
||||
feat: allow config to extend other configs
|
||||
|
||||
BREAKING CHANGE: `extends` key now used for extending config files
|
||||
```
|
||||
|
||||
**Both together** (most explicit):
|
||||
```
|
||||
feat!: drop support for Node 6
|
||||
|
||||
BREAKING CHANGE: use JavaScript features not available in Node 6.
|
||||
```
|
||||
|
||||
Rules:
|
||||
- `BREAKING CHANGE` must be all caps.
|
||||
- `BREAKING-CHANGE` (hyphenated) is an accepted synonym.
|
||||
- Any type can carry a breaking change, not just `feat`.
|
||||
- The footer value must describe what broke.
|
||||
|
||||
## Footer Token Rules
|
||||
|
||||
```
|
||||
<token>: <value>
|
||||
<token> #<value> # for issue references
|
||||
```
|
||||
|
||||
- Tokens use hyphens for word separation: `Reviewed-by`, `Co-authored-by`, `Refs`.
|
||||
- Exception: `BREAKING CHANGE` (space allowed, uppercase).
|
||||
- Multiple footers allowed, one per line.
|
||||
- Blank line required before the footer block.
|
||||
|
||||
Valid footer examples:
|
||||
```
|
||||
Reviewed-by: Z
|
||||
Refs: #123
|
||||
Co-authored-by: Alice <alice@example.com>
|
||||
BREAKING CHANGE: the `--format` flag now requires a value
|
||||
```
|
||||
|
||||
## Examples
|
||||
|
||||
Minimal — no body, no footer:
|
||||
```
|
||||
docs: correct spelling of CHANGELOG
|
||||
```
|
||||
|
||||
With scope:
|
||||
```
|
||||
feat(lang): add Polish language
|
||||
```
|
||||
|
||||
Breaking change via `!`:
|
||||
```
|
||||
feat!: send an email to the customer when a product is shipped
|
||||
```
|
||||
|
||||
Breaking change via footer:
|
||||
```
|
||||
feat: allow provided config object to extend other configs
|
||||
|
||||
BREAKING CHANGE: `extends` key in config file is now used for extending other config files
|
||||
```
|
||||
|
||||
Multi-paragraph body with multiple footers:
|
||||
```
|
||||
fix: prevent racing of requests
|
||||
|
||||
Introduce a request id and a reference to latest request. Dismiss
|
||||
incoming responses other than from latest request.
|
||||
|
||||
Remove timeouts which were used to mitigate the racing issue but are
|
||||
obsolete now.
|
||||
|
||||
Reviewed-by: Z
|
||||
Refs: #123
|
||||
```
|
||||
|
||||
Revert:
|
||||
```
|
||||
revert: let us never again speak of the noodle incident
|
||||
|
||||
Refs: 676104e, a215868
|
||||
```
|
||||
|
||||
## commitlint Constraints (config-conventional)
|
||||
|
||||
| Constraint | Value |
|
||||
|---|---|
|
||||
| Header max length | 100 characters |
|
||||
| Subject must not end with `.` | enforced |
|
||||
| Subject must be lowercase (not sentence-case or UPPER-CASE) | enforced |
|
||||
| Body / footer line max length | 100 characters |
|
||||
| Type must be one of the 11 standard types | error if not |
|
||||
| Blank line before body | warning |
|
||||
| Blank line before footer | warning |
|
||||
|
||||
## SemVer Mapping Summary
|
||||
|
||||
| Condition | SemVer bump |
|
||||
|---|---|
|
||||
| `fix`, `perf`, `revert` | PATCH |
|
||||
| `feat` | MINOR |
|
||||
| Any type with `BREAKING CHANGE` or `!` | MAJOR |
|
||||
| All other types (`docs`, `style`, `refactor`, `test`, `build`, `ci`, `chore`) | none |
|
||||
40
plugins/git/skills/git-commits/references/sources.md
Normal file
40
plugins/git/skills/git-commits/references/sources.md
Normal file
@@ -0,0 +1,40 @@
|
||||
---
|
||||
topic: commits
|
||||
source_keys:
|
||||
- conventional-commits-spec
|
||||
- commitlint-config-conventional
|
||||
- org-commit-conventions
|
||||
- context7-git-htmldocs
|
||||
---
|
||||
|
||||
# Research Sources for git:commits Skill
|
||||
|
||||
Sources extracted from the git plugin research phase. Only sources that directly informed this skill are listed; sibling skills (git:branches, git:history, git:remotes, etc.) have their own sources.md.
|
||||
|
||||
## conventional-commits-spec
|
||||
|
||||
- **Description:** Conventional Commits Specification (v1.0.0) — message format, types, breaking changes, footer rules
|
||||
- **Research doc:** plugins/git/docs/research/docs/git/commits.md § "Conventional Commits Specification (v1.0.0)"
|
||||
- **Contributing files:** SKILL.md, references/conventional-commits-spec.md
|
||||
- **Status:** extracted
|
||||
|
||||
## commitlint-config-conventional
|
||||
|
||||
- **Description:** commitlint config-conventional preset — validation constraints (max 100 chars header, no trailing periods, lowercase type, 11-type set enforcement)
|
||||
- **Research doc:** plugins/git/docs/research/docs/git/commits.md § "commitlint Constraints (`config-conventional`)"
|
||||
- **Contributing files:** SKILL.md, references/conventional-commits-spec.md
|
||||
- **Status:** extracted
|
||||
|
||||
## org-commit-conventions
|
||||
|
||||
- **Description:** Organization commit message body template and git conventions (atomic commits, no `--no-verify`, no force-push main/master, `rtk git` wrapper) — content fully embedded in this skill; the org's `core/instructions/git.md` and `core/instructions/commits.md` are provenance only and are not a live dependency
|
||||
- **Research doc:** core/instructions/commits.md, core/instructions/git.md (org convention, not part of the plugin's research corpus)
|
||||
- **Contributing files:** SKILL.md, references/commit-template.md
|
||||
- **Status:** extracted
|
||||
|
||||
## context7-git-htmldocs
|
||||
|
||||
- **Description:** Official Git HTML documentation — `git commit --squash`/`--fixup` and `git rebase --autosquash` flag semantics
|
||||
- **Research doc:** plugins/git/docs/research/docs/git/cli-reference.md
|
||||
- **Contributing files:** SKILL.md
|
||||
- **Status:** extracted
|
||||
Reference in New Issue
Block a user