git-workflow

Files (1)

• SKILL.md

SKILL.md (first lines)

# Git Workflow Skill

Use this skill whenever the task involves git.

## When to Activate

- Creating or renaming branches
- Staging changes
- Writing commit messages
- Creating commits
- Pushing branches
- Preparing pull requests
- Reviewing branch names or commit message format

## Required Delegation

When git work is needed: if the `git-specialist` agent is installed, delegate to that agent via the `/git` command. Otherwise the main agent does the work inline by following this skill.

- If `git-specialist` is installed, do not handle substantive git workflow in the main agent when `/git` can handle it. Otherwise the main agent does that git work inline.
- If `git-specialist` is installed, that agent owns branch naming, commit message drafting, staging, commits, and pushes. Otherwise the main agent does those inline.
- Keep non-git implementation work in the main agent. If `git-specialist` is installed, switch to `/git` for repository operations. Otherwise stay in this session and follow this skill.
- If you are already the `git-specialist` agent, execute the git task directly and do not re-delegate it. Follow the Canonical spec section below.

## Commit Convention

Every commit message must follow this format:

```text
<type>(<scope>): <short summary>

[optional body]

[optional footer(s)]
```

When scope is not useful or not clear, this no-scope form is also valid:

```text
<type>: <short summary>
```

### Allowed Types

- `feat`: A new feature
- `fix`: A bug fix
- `docs`: Documentation only changes
- `style`: Changes that do not affect behavior, such as formatting
- `refactor`: Code changes that neither fix a bug nor add a feature
- `test`: Adding or correcting tests
- `chore`: Maintenance tasks such as tooling or build updates

### Commit Rules

- **English only**: subject and body MUST be English, even when the diff or conversation is French.
- Prefer including a meaningful `scope` when the affected area is clear
- Omit `scope` instead of inventing one when it is not clear
- Use a concise present-tense summary
- Keep the summary focused on intent, not a file-by-file changelog
- Match the type to the actual purpose of the change

### Examples

- `feat(api): add user authentication endpoint`
- `fix(auth): prevent empty login submission`
- `chore(settings): sync opencode configuration`

## Branch Convention

Every branch name must follow this format:

```text
<type>/<scope>-<short-description>
```

### Branch Rules

- Reuse the same allowed `type` values as commits
- `scope` is required for branches
- `scope` must be a single lowercase token with letters and numbers only
- The first `-` after `/` separates `scope` from `short-description`
- Use a short kebab-case description
- Keep the branch name specific to the actual change
- If branch scope is ambiguous, ask one short question before creating the branch

### Examples

- `feat/auth-login-form`
- `fix/api-token-refresh`
- `chore/settings-git-workflow`

## Git Specialist Expectations

If the `git-specialist` agent is installed, it must follow this list. Otherwise the main agent follows the same list inline.

- inspect repository status before acting
- draft compliant branch names and commit messages
- stage only relevant changes
- avoid destructive git commands unless explicitly requested
- push only when requested or clearly part of the delegated git task
- detect the host from `git remote get-url origin` and use the matching CLI for PR work: `gh` for GitHub, `az repos pr` for Azure DevOps
- preserve repository history hygiene

## Pull Request Rules

When the task includes PR creation or inspection:

- Follow the `pr-visual-report` skill before opening or updating the PR. Run `agent-harness kpi feature` before rendering the HTML (Conductor and Monolith). Commit `docs/pr-reports/<branch-slug>.html`, `.png`, and `.metrics.json`, and include `## Visual report` plus the metrics table in the body. `agent-harness pr-report-check` checks the body and warns when metrics are missing or partial. The hook blocks `gh` and `az` when the visual section is missing. A docs typo or a version bump only may skip, with the reason on the skip line.
- detect the host from `git remote get-url origin`:
  - `github.com` → use `gh`
  - `dev.azure.com` / `visualstudio.com` → use `az repos pr` (Azure CLI + `azure-devops` extension)
  - otherwise → stop and report an unsupported host
- push the current branch with upstream tracking first if needed
- if a PR already exists for the current branch, return that URL instead of creating a duplicate
- choose the base branch from the repository default branch when available, otherwise prefer `main`, then `master`
- use a concise PR title aligned with the branch purpose and commit intent (conventional commit format)
- include a short `## Summary` section in the PR body
- Azure DevOps defaults: reviewers = group `PIXELS`; `--draft` is not supported by `az repos pr` (ignore the flag for Azure)

## Output Expectations

From fmflurry/settings-opencode, MIT.

More from fmflurry/settings-opencode