wmasfoe/md-editor / .agents/skills/git-workflow
git-workflow
VerifiedStandard 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 usefeat/<name>;featis for commit types, while branches must usefeature/) - Bug Fixes:
fix/<name>orhotfix/<name> - Refactoring:
refactor/<name> - Documentation:
docs/<name> - Performance:
perf/<name> - CI / Build:
ci/<name>orchore/<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 tofeat/) - ❌
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:
# 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:
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:
git push origin <branch>
Automated CI Watch
If the current branch has an associated open Pull Request, the agent MUST automatically monitor CI status:
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:
# 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, orbeta. - Merging with
--delete-branchensures already-merged feature/fix branches do not accumulate as stale branches. - After merging, switch back to
mainand pull the latest changes: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:
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):
- Before pushing or opening a PR:
If changes affect any of the public npm packages above, generate a changeset fragment:
Select affected package(s), select SemVer type (pnpm changesetpatch/minor/major), and provide a clear English change description. - Commit changeset file:
Commit the generated
.changeset/*.mdfile with your PR:git add .changeset/*.md - DO NOT manually bump version in package.json:
Versions, changelogs, and npm distribution are handled automatically by Changesets when merging into
main. - CI Changeset Guard:
The PR
lintjob runsnode scripts/packages/check-changeset.mjs. If public packages are touched without a changeset, it warns the PR author. - Release Trigger (For Maintainers):
- Ensure
NPM_TOKENis configured in GitHub Repository Secrets (Settings -> Secrets and variables -> Actions). - Merging changesets into
mainautomatically 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 executespnpm verify:packagesand publishes updated packages to npm with Git tags.
- Ensure
- Detailed Documentation:
See
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: 118k | 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: 117k | 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 |