# WORKFLOWS.md

## Commit Messages
Format: `type: short description`

Types: `feat`, `fix`, `style`, `refactor`, `chore`, `docs`, `perf`

Under 72 chars, lowercase, no trailing period. Be specific — never "fix bug", "update file", "wip". Never add Co-Authored-By or mention Claude/AI. Never use heredoc syntax — always `git commit -m "type: description"`.

## Creating a PR
Only when told "create a PR" or "ready for PR":
1. `git fetch origin`
2. `git pull origin develop`
3. Create branch if not on one: `feat/short-description` or `fix/short-description`
4. Ensure all changes are committed with proper format
5. Run lint and format checks; fix errors
6. Push the branch
7. Create PR with description of what changed and why
8. Report back with PR link

Never work on or push to main directly.

## Merging and Pushing
Always pull the target branch before merging. Never skip steps.

The integration branch may be `develop` or `development`. On first merge, run `git branch -r` to check which exists. If both exist, ask.

**To develop/development:**
1. `git checkout develop || git checkout development`
2. `git fetch origin && git pull origin develop`
3. `git merge feat/your-branch`
4. Resolve conflicts, confirm before continuing
5. `git push origin develop`

**To staging:** Same steps but checkout staging, pull staging, merge the feature branch directly. Never merge develop into staging.

Never push to main directly. If any step fails, stop and report exactly what failed.

## Multi-Repo Changes
When a change spans multiple related repos (e.g. this plugin, `paca-ai-worker-js`, `paca-ai-streaming-subscription`), use the identical branch name in every repo and run the same branch → commit → push sequence in each one before moving to the next — keeps the related work easy to track and merge together.

## Push Authentication
If `git push` fails with `Permission denied (publickey)`, push over HTTPS instead: `git -c credential.helper="!gh auth git-credential" push -u https://github.com/<owner>/<repo>.git <branch>:<branch>`.

## PR Description Format
**Type: Short description**

One or two sentences explaining the problem or feature, human-friendly.

Changes:
- Specific bullet per change
- Note files intentionally untouched if relevant

Under 10 lines. No changelog-speak ("leveraging", "utilizing", "redundant"). Write like a teammate. Never mention Claude, AI, or co-authors.