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

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:

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

PlatformCommandTag PatternCI Workflow
Desktoppnpm release:desktopv*.github/workflows/release-desktop.yml
Webpnpm release:webweb-v*.github/workflows/release-web.yml
Sitepnpm release:siteN/AVercel CLI Prebuilt Deploy
Workerpnpm deploy:workerN/ACloudflare 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:
    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:
    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.
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: 118kUpdated 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: 117kUpdated 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