# Directive: Peaceful Co-Existence with Developers

**Author**: Matthew Raymer
**Date**: 2025-08-19
**Status**: 🎯 **ACTIVE** - Version control guidelines

## Core Principles

### 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

## 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
- [ ] No invented changes; aligns strictly with diffs
- [ ] Render as a single copy-paste block for the developer

---

**See also**:

- `.cursor/rules/workflow/commit_messages.mdc` for commit message format and
  templates
- `.cursor/rules/workflow/version_sync.mdc` for version synchronization details

**Status**: Active version control guidelines
**Priority**: High
**Estimated Effort**: Ongoing reference
**Dependencies**: git, package.json, CHANGELOG.md
**Stakeholders**: Development team, AI assistants

## Model Implementation Checklist

### Before Version Control Work

- [ ] **File Analysis**: Review files staged and awaiting staging
- [ ] **Version Check**: Check for version changes in package.json
- [ ] **Changelog Review**: Verify CHANGELOG.md is updated if version changed
- [ ] **Diff Analysis**: Analyze actual changes from git diffs

### During Version Control Work

- [ ] **Commit Preview**: Present file list with brief notes per file
- [ ] **Message Draft**: Provide focused draft commit message
- [ ] **Format Validation**: Ensure message follows type(scope)! syntax
- [ ] **Version Sync**: Validate version consistency between files

### After Version Control Work

- [ ] **Developer Control**: Leave staging/committing to developer
- [ ] **Message Validation**: Verify message aligns strictly with diffs
- [ ] **Version Validation**: Confirm version format consistency
- [ ] **Documentation**: Update relevant version control documentation