Skip to content

wmasfoe/md-editor / .agents/skills/git-workflow

git-workflow

Verified

Standard Git commit, verification, push, and CI watch workflow for md-editor

FileKindSize
SKILL.mdskill md6.7 KB
---
name: git-workflow
description: "Standard Git commit, verification, push, and CI watch workflow for md-editor"
---

# Git Workflow & Pre-Push Quality Protocol

This skill guides agents through the mandatory lifecycle for branching, committing, verifying, pushing code, and monitoring CI checks in the `md-editor` workspace.

## 1. Branch Naming Protocol (Mandatory)

All git branches MUST follow the `<category>/<kebab-case-description>` pattern:
- **Features**: `feature/<name>` (⚠️ **STRICTLY FORBIDDEN to use `feat/<name>`**; `feat` is for commit types, while branches must use `feature/`)
- **Bug Fixes**: `fix/<name>` or `hotfix/<name>`
- **Refactoring**: `refactor/<name>`
- **Documentation**: `docs/<name>`
- **Performance**: `perf/<name>`
- **CI / Build**: `ci/<name>` or `chore/<name>`

### Examples
- ✅ `feature/desktop-r2-distribution`
- ✅ `feature/mobile-editor-core`
- ✅ `fix/table-cell-editing`
- ✅ `refactor/split-desktop-view`
- ❌ `feat/desktop-r2-distribution` (Do NOT abbreviate to `feat/`)
- ❌ `update-something` (Missing category prefix)

---

## 2. Commit Protocol (Mandatory Conventional Commits)

All commit messages MUST strictly adhere to the Conventional Commits specification:

```
<type>(<scope>): <subject>

[optional body]

[optional footer(s)]
```

### Allowed Types
- `feat`: A new feature or capability (e.g. `feat(renderer): add dynamic plugin registration`)
- `fix`: A bug fix (e.g. `fix(wysiwyg): calibrate code-block drag alignment`)
- `perf`: A code change that improves performance (e.g. `perf(parser): bypass ast rebuild for ui plugins`)
- `refactor`: A code change that neither fixes a bug nor adds a feature (e.g. `refactor(plugins): decouple syntax plugins to subpackage`)
- `docs`: Documentation only changes (e.g. `docs: update plugin development guide`)
- `test`: Adding or correcting tests (e.g. `test(core): add regression tests for markdown fidelity`)
- `chore`: Changes to build process, dependencies, or tooling (e.g. `chore: update dependencies`)
- `style`: Formatting or whitespace fixes (e.g. `style: format markdown tables`)
- `ci`: Changes to CI configuration or workflow files (e.g. `ci: add automated desktop release`)

### Disallowed Patterns
- ❌ No arbitrary capitalized sentences (e.g. `Update some files`, `Fixed bug`)
- ❌ No Lore trailers (`Constraint:`, `Rejected:`, `Directive:`, `Confidence:`)
- ❌ No vague messages (e.g. `wip`, `misc fixes`)

---

## 3. Pre-Push Verification (Mandatory)

Before executing `git push`, the agent MUST run and ensure the following checks pass:

```bash
# 1. Check linting, Prettier formatting, and Rust cargo clippy/fmt
pnpm lint

# 2. Run unit tests across all workspaces (unit tests must pass 100%; e2e is optional)
pnpm test

# 3. Verify TypeScript types across all workspaces
pnpm typecheck
```

Alternatively, run the unified verification script:
```bash
pnpm verify
```

If ANY of these commands fail:
- DO NOT proceed to push.
- Investigate and fix the issue first.
- Re-run verification until all commands exit with code 0.

---

## 4. Push and Post-Push CI Monitoring (Mandatory)

After pushing changes to the remote branch:

```bash
git push origin <branch>
```

### Automated CI Watch
If the current branch has an associated open Pull Request, the agent MUST automatically monitor CI status:

```bash
pnpm pr:watch
# or:
gh pr checks <pr_number> --watch
```

### Reporting
- If all checks pass: Report the success and active PR link to the user.
- If any check fails: Inspect the failed step log (`gh run view --log-failed`), identify the failure reason, and either fix it or provide a detailed diagnostic report.

---

## 5. Pull Request Merge & Branch Cleanup Protocol (Mandatory)

When merging a Pull Request using GitHub CLI (`gh pr merge`), **ALWAYS include the `--delete-branch` (`-d`) flag** to automatically delete both the remote branch and local tracking branch after merge:

```bash
# Recommended squash-and-merge with automatic branch deletion:
gh pr merge <pr_number_or_url> --squash --delete-branch

# Or with auto-merge enabled (automatically merges and deletes branch once CI passes):
gh pr merge <pr_number_or_url> --squash --auto --delete-branch
```

### Safety Rules for Branch Deletion:
- **Protected Branches**: NEVER delete `main`, `dev`, or `beta`.
- Merging with `--delete-branch` ensures already-merged feature/fix branches do not accumulate as stale branches.
- After merging, switch back to `main` and pull the latest changes:
  ```bash
  git checkout main && git pull origin main
  ```

---

## 6. Multi-Platform Release Protocol

For multi-platform releases, version bumps, changelog maintenance, and production deployment, refer to the dedicated **Release Skill**:
- [`.agents/skills/release/SKILL.md`](../release/SKILL.md)

### Release Command Quick Reference

| Platform | Command | Tag Pattern | CI Workflow |
| :--- | :--- | :--- | :--- |
| **Desktop** | `pnpm release:desktop` | `v*` | `.github/workflows/release-desktop.yml` |
| **Web** | `pnpm release:web` | `web-v*` | `.github/workflows/release-web.yml` |
| **Site** | `pnpm release:site` | N/A | Vercel CLI Prebuilt Deploy |
| **Worker** | `pnpm deploy:worker` | N/A | Cloudflare Worker CLI |

---

## 7. Public NPM Packages Release Protocol (Changesets)

For public npm packages (`packages/core`, `packages/editor`, `packages/plugin-sdk`, `packages/shared`, `packages/markdown-fidelity`, `packages/plugin-host`):

1. **Before pushing or opening a PR**:
   If changes affect any of the public npm packages above, generate a changeset fragment:
   ```bash
   pnpm changeset
   ```
   Select affected package(s), select SemVer type (`patch` / `minor` / `major`), and provide a clear English change description.
2. **Commit changeset file**:
   Commit the generated `.changeset/*.md` file with your PR:
   ```bash
   git add .changeset/*.md
   ```
3. **DO NOT manually bump version in package.json**:
   Versions, changelogs, and npm distribution are handled automatically by Changesets when merging into `main`.
4. **CI Changeset Guard**:
   The PR `lint` job runs `node scripts/packages/check-changeset.mjs`. If public packages are touched without a changeset, it warns the PR author.
5. **Release Trigger (For Maintainers)**:
   - Ensure `NPM_TOKEN` is configured in GitHub Repository Secrets (**Settings -> Secrets and variables -> Actions**).
   - Merging changesets into `main` automatically creates/updates the **"chore(release): version npm packages"** PR via `.github/workflows/release-npm-packages.yml`.
   - Merging that release PR triggers `pnpm release:packages`, which executes `pnpm verify:packages` and publishes updated packages to npm with Git tags.
6. **Detailed Documentation**:
   See [`docs/agent/release/npm_automated_release_changesets.md`](../../../docs/agent/release/npm_automated_release_changesets.md).



planning-and-task-breakdownaddyosmani/agent-skillsBreaks work into ordered tasks. Use when you have a spec or clear requirements and need to break work into implementable tasks. Use when a task feels too large to start, when you need to estimate scope, or when parallel work is possible.Stars: 119kUpdated Claude CodeCodexVerifiedInstall
screenpipethedotmack/claude-memSearch screen and audio history recorded by Screenpipe and optionally save selected context into claude-mem. Use when the user asks to recall desktop activity, a meeting, or something seen in another app through Screenpipe.Stars: 118kUpdated Claude CodeCodexVerifiedInstall
contact-widgetnexu-io/open-designSelf-contained floating chat widget with welcome screen, social links, meeting button, and message input. Single HTML file, zero dependencies.Stars: 108kUpdated Claude CodeCodexVerifiedInstall
meeting-notesnexu-io/open-designMeeting notes page — title bar with attendees, agenda checklist, decisions block, action items table with owners + dates, and a "next meeting" footer. Use when the brief mentions "meeting notes", "minutes", "1:1 notes", "all-hands recap", or "会议纪要".Stars: 108kUpdated Claude CodeCodexVerifiedInstall