wmasfoe/md-editor / .agents/skills/git-workflow
git-workflow
VerifiedStandard Git commit, verification, push, and CI watch workflow for md-editor
| File | Kind | Size |
|---|---|---|
| SKILL.md | skill md | 6.7 KB |
SKILL.md
View on GitHub---
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).
Related skills
| Skill | Stars | Updated | Works with | Status | Install |
|---|---|---|---|---|---|
| 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: 119k | Updated | Claude CodeCodex | Verified | Install |
| 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: 118k | Updated | Claude CodeCodex | Verified | Install |
| 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: 108k | Updated | Claude CodeCodex | Verified | Install |
| 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: 108k | Updated | Claude CodeCodex | Verified | Install |