forked from trent_larson/crowd-funder-for-time-pwa
1a06dea491
- Add Version Synchronization Requirements section for package.json/CHANGELOG.md sync - Include Version Sync Checklist with pre-commit validation steps - Add Version Change Detection guidelines for identifying version mismatches - Include Implementation Notes for semantic versioning and changelog standards - Ensure version bump commits follow proper format and documentation - Maintain existing human control requirements while adding version sync enforcement Improves release quality and prevents version drift between package.json and CHANGELOG.md
154 lines
4.7 KiB
Plaintext
154 lines
4.7 KiB
Plaintext
---
|
||
alwaysApply: true
|
||
---
|
||
# Directive: Peaceful Co-Existence with Developers
|
||
|
||
## 1) Version-Control Ownership
|
||
|
||
* **MUST NOT** run `git add`, `git commit`, or any write action.
|
||
* **MUST** leave staging/committing to the developer.
|
||
|
||
## 2) Source of Truth for Commit Text
|
||
|
||
* **MUST** derive messages **only** from:
|
||
|
||
* files **staged** for commit (primary), and
|
||
* files **awaiting staging** (context).
|
||
* **MUST** use the **diffs** to inform content.
|
||
* **MUST NOT** invent changes or imply work not present in diffs.
|
||
|
||
## 3) Mandatory Preview Flow
|
||
|
||
* **ALWAYS** present, before any real commit:
|
||
|
||
* file list + brief per-file notes,
|
||
* a **draft commit message** (copy-paste ready),
|
||
* nothing auto-applied.
|
||
|
||
## 4) Version Synchronization Requirements
|
||
|
||
* **MUST** check for version changes in `package.json` before committing
|
||
* **MUST** ensure `CHANGELOG.md` is updated when `package.json` version changes
|
||
* **MUST** validate version format consistency between both files
|
||
* **MUST** include version bump commits in changelog with proper semantic versioning
|
||
|
||
### Version Sync Checklist (Before Commit)
|
||
|
||
- [ ] `package.json` version matches latest `CHANGELOG.md` entry
|
||
- [ ] New version follows semantic versioning (MAJOR.MINOR.PATCH[-PRERELEASE])
|
||
- [ ] Changelog entry includes all significant changes since last version
|
||
- [ ] Version bump commit message follows `build(version): bump to X.Y.Z` format
|
||
- [ ] Breaking changes properly documented with migration notes
|
||
- [ ] Alert developer in chat message that version has been updated
|
||
|
||
### Version Change Detection
|
||
|
||
* **Check for version changes** in staged/unstaged `package.json`
|
||
* **Alert developer** if version changed but changelog not updated
|
||
* **Suggest changelog update** with proper format and content
|
||
* **Validate semantic versioning** compliance
|
||
|
||
### Implementation Notes
|
||
|
||
* **Version Detection**: Compare `package.json` version field with latest changelog entry
|
||
* **Semantic Validation**: Ensure version follows `X.Y.Z[-PRERELEASE]` format
|
||
* **Changelog Format**: Follow [Keep a Changelog](https://keepachangelog.com/) standards
|
||
* **Breaking Changes**: Use `!` in commit message and `BREAKING CHANGE:` in changelog
|
||
* **Pre-release Versions**: Include beta/alpha/rc suffixes in both files consistently
|
||
|
||
---
|
||
|
||
# Commit Message Format (Normative)
|
||
|
||
## A. Subject Line (required)
|
||
|
||
```
|
||
<type>(<scope>)<!>: <summary>
|
||
```
|
||
|
||
* **type** (lowercase, Conventional Commits): `feat|fix|refactor|perf|docs|test|build|chore|ci|revert`
|
||
* **scope**: optional module/package/area (e.g., `api`, `ui/login`, `db`)
|
||
* **!**: include when a breaking change is introduced
|
||
* **summary**: imperative mood, ≤ 72 chars, no trailing period
|
||
|
||
**Examples**
|
||
|
||
* `fix(api): handle null token in refresh path`
|
||
* `feat(ui/login)!: require OTP after 3 failed attempts`
|
||
|
||
## B. Body (optional, when it adds non-obvious value)
|
||
|
||
* One blank line after subject.
|
||
* Wrap at \~72 chars.
|
||
* Explain **what** and **why**, not line-by-line “how”.
|
||
* Include brief notes like tests passing or TS/lint issues resolved **only if material**.
|
||
|
||
**Body checklist**
|
||
|
||
* [ ] Problem/symptom being addressed
|
||
* [ ] High-level approach or rationale
|
||
* [ ] Risks, tradeoffs, or follow-ups (if any)
|
||
|
||
## C. Footer (optional)
|
||
|
||
* Issue refs: `Closes #123`, `Refs #456`
|
||
* Breaking change (alternative to `!`):
|
||
`BREAKING CHANGE: <impact + migration note>`
|
||
* Authors: `Co-authored-by: Name <email>`
|
||
* Security: `CVE-XXXX-YYYY: <short note>` (if applicable)
|
||
|
||
---
|
||
|
||
## Content Guidance
|
||
|
||
### Include (when relevant)
|
||
|
||
* Specific fixes/features delivered
|
||
* Symptoms/problems fixed
|
||
* Brief note that tests passed or TS/lint errors resolved
|
||
|
||
### Avoid
|
||
|
||
* Vague: *improved, enhanced, better*
|
||
* Trivialities: tiny docs, one-liners, pure lint cleanups (separate, focused commits if needed)
|
||
* Redundancy: generic blurbs repeated across files
|
||
* Multi-purpose dumps: keep commits **narrow and focused**
|
||
* Long explanations that good inline code comments already cover
|
||
|
||
**Guiding Principle:** Let code and inline docs speak. Use commits to highlight what isn’t obvious.
|
||
|
||
---
|
||
|
||
# Copy-Paste Templates
|
||
|
||
## Minimal (no body)
|
||
|
||
```text
|
||
<type>(<scope>): <summary>
|
||
```
|
||
|
||
## Standard (with body & footer)
|
||
|
||
```text
|
||
<type>(<scope>)<!>: <summary>
|
||
|
||
<why-this-change?>
|
||
<what-it-does?>
|
||
<risks-or-follow-ups?>
|
||
|
||
Closes #<id>
|
||
BREAKING CHANGE: <impact + migration>
|
||
Co-authored-by: <Name> <email>
|
||
```
|
||
|
||
---
|
||
|
||
# Assistant Output Checklist (before showing the draft)
|
||
|
||
* [ ] List changed files + 1–2 line notes per file
|
||
* [ ] Provide **one** focused draft message (subject/body/footer)
|
||
* [ ] Subject ≤ 72 chars, imperative mood, correct `type(scope)!` syntax
|
||
* [ ] Body only if it adds non-obvious value
|
||
* [ ] No invented changes; aligns strictly with diffs
|
||
* [ ] Render as a single copy-paste block for the developer
|