When to use this skill
Load this skill when creating branches, writing commit messages, reviewing commit history, planning change sizing, or setting up CI/CD that depends on commit parsing (changelogs, version bumps, release notes). Read .opencode/agents/_workflow.md first — it is the canonical contract; this skill is the operational detail.
Overview
This squad uses a gitflow-style discipline with a single protected long-lived branch (main), short-lived issue-scoped branches, mandatory PR reviews, and green CI before merge. Conventional Commits power changelog and release tooling.
Important policy change. Earlier versions of this skill described a trunk-based workflow. That is superseded. main is now protected; all changes land via reviewed PR.
The non-negotiables
main is protected. No direct commits, no force pushes, no bypass.- Every branch is tied to an Issue. Branch name encodes the Issue number.
- Never push to remote unless the user has explicitly asked in this session.
Local commits are fine.
git push, gh pr create, and any
gh_*_create_pull_request / gh_*_merge_pull_request require explicit
authorization.
- Always pull latest before starting work.
git fetch --all --prune then
git pull --rebase origin main. If you have uncommitted changes, stop and
ask before pulling.
- Conventional Commits, every commit, with Issue reference.
Branch strategy
Branches
main — protected, always green, always deployable.- Issue branches — short-lived (1–3 days), branched from
main, merged
back via PR.
- No long-running
develop / staging / release branches. Use feature
flags for incomplete work.
Branch naming
<type>/<issue#>-<short-slug>
| Type |
When |
feature/ |
New feature or user-facing enhancement |
fix/ |
Bug fix |
refactor/ |
Code restructuring with no behaviour change |
chore/ |
Tooling, config, dependency updates |
docs/ |
Documentation-only changes |
test/ |
Adding or fixing tests |
Examples: feature/42-due-date-filter, fix/87-null-localstorage,
refactor/91-extract-hook, chore/16-universal-workflow-contract.
Slug: kebab-case, lowercase, ≤ 5 words, summarises intent.
Commit conventions
Conventional Commits format
<type>(<scope>): <imperative description> (#NNN)
[optional body — what and why, wrap 72 chars]
[optional footer — Closes #NNN, BREAKING CHANGE: ...]
| Type |
Description |
feat |
New feature |
fix |
Bug fix |
refactor |
Code change with no behaviour change |
test |
Adding or modifying tests |
docs |
Documentation |
chore |
Maintenance, config, deps |
style |
Formatting, whitespace (no logic) |
perf |
Performance improvement |
ci |
CI configuration |
build |
Build system / external deps |
Examples:
feat(todos): add due-date filter dropdown (#42)
fix(useTodos): handle null localStorage on initial load (#87)
refactor(TodoItem): extract LabelList sub-component (#91)
Commit rules
- One logical change per commit. Not "fix stuff".
- Imperative mood: "add feature", not "added feature".
- No trailing period on the subject line.
- Reference the Issue with
(#NNN) in the subject or Closes #NNN in the
footer.
- Body explains WHAT and WHY, not HOW.
Change sizing
| Size |
Lines changed |
Scope |
| XS |
1–20 |
Single function, config tweak |
| S |
20–50 |
Small component change |
| M |
50–100 |
One feature slice |
| L |
100–300 |
Multi-file feature — consider splitting |
| XL |
300+ |
Must split into multiple commits |
Rule of ~100: aim for ~100 lines per commit. Larger diffs are harder to
review and more likely to contain bugs.
Atomic commits
Each commit must:
- Compile and pass tests (
git bisect-friendly).
- Contain one coherent change — not a WIP dump.
- Be independently revertable.
Squash temporary commits before merging.
PR discipline
- PR title mirrors the lead commit's subject.
- PR description follows the project's template and includes:
Closes #NNN, summary, screenshots if UI, test plan, rollback plan.
- Reviewers requested per CODEOWNERS or role.
- CI must be green before merge.
- Merge strategy: squash by default (one Issue → one commit on
main).
Use merge commit only when commits are already atomic and meaningful.
Push & PR authorization
- Local commits: always fine.
git push, gh pr create, gh_*_create_pull_request,
gh_*_merge_pull_request: only with explicit user authorization for that
action in the current session.- If unsure, ask the user. Default to NOT pushing.
Common rationalisations
| Rationalisation |
Reality |
| "I'll clean up the commits later." |
Later never arrives. Squash before opening a PR. |
| "This is just a small fix, no need for a branch." |
Every change gets a branch. No exceptions. |
| "The commit message is obvious from the diff." |
The diff shows WHAT, not WHY. The message captures intent. |
| "I'll push now and clean up after." |
No. Pushing changes the contract with the team and triggers CI. |
Red flags
- Commits titled "fix", "update", "stuff", "WIP".
- Branches with many authors or lasting more than a few days.
- Large diffs (300+ lines) in a single commit.
- Commits that don't compile or fail tests.
- Pushes that were not explicitly authorized.
Verification
Source: mtel-thailand/ai-template — distributed by TomeVault.
1---2name: git-workflow-and-versioning-173description: Gitflow-style Git workflow with protected main, issue-scoped branches, Conventional Commits, atomic commits, and the never-push-without-explicit-request rule. Load when branching, committing, planning change sizing, or setting up release tooling. Use when this capability is needed.4---56## When to use this skill78Load this skill when creating branches, writing commit messages, reviewing commit history, planning change sizing, or setting up CI/CD that depends on commit parsing (changelogs, version bumps, release notes). Read `.opencode/agents/_workflow.md` first — it is the canonical contract; this skill is the operational detail.910## Overview1112This squad uses a gitflow-style discipline with a single protected long-lived branch (`main`), short-lived issue-scoped branches, mandatory PR reviews, and green CI before merge. Conventional Commits power changelog and release tooling.1314> **Important policy change.** Earlier versions of this skill described a *trunk-based* workflow. That is superseded. `main` is now protected; all changes land via reviewed PR.1516## The non-negotiables17181. **`main` is protected.** No direct commits, no force pushes, no bypass.192. **Every branch is tied to an Issue.** Branch name encodes the Issue number.203. **Never push to remote unless the user has explicitly asked in this session.**21 Local commits are fine. `git push`, `gh pr create`, and any22 `gh_*_create_pull_request` / `gh_*_merge_pull_request` require explicit23 authorization.244. **Always pull latest before starting work.** `git fetch --all --prune` then25 `git pull --rebase origin main`. If you have uncommitted changes, stop and26 ask before pulling.275. **Conventional Commits, every commit, with Issue reference.**2829## Branch strategy3031### Branches32- **`main`** — protected, always green, always deployable.33- **Issue branches** — short-lived (1–3 days), branched from `main`, merged34 back via PR.35- No long-running `develop` / `staging` / `release` branches. Use feature36 flags for incomplete work.3738### Branch naming39```40<type>/<issue#>-<short-slug>41```4243| Type | When |44|------|------|45| `feature/` | New feature or user-facing enhancement |46| `fix/` | Bug fix |47| `refactor/` | Code restructuring with no behaviour change |48| `chore/` | Tooling, config, dependency updates |49| `docs/` | Documentation-only changes |50| `test/` | Adding or fixing tests |5152Examples: `feature/42-due-date-filter`, `fix/87-null-localstorage`,53`refactor/91-extract-hook`, `chore/16-universal-workflow-contract`.5455Slug: kebab-case, lowercase, ≤ 5 words, summarises intent.5657## Commit conventions5859### Conventional Commits format60```61<type>(<scope>): <imperative description> (#NNN)6263[optional body — what and why, wrap 72 chars]6465[optional footer — Closes #NNN, BREAKING CHANGE: ...]66```6768| Type | Description |69|------|-------------|70| `feat` | New feature |71| `fix` | Bug fix |72| `refactor` | Code change with no behaviour change |73| `test` | Adding or modifying tests |74| `docs` | Documentation |75| `chore` | Maintenance, config, deps |76| `style` | Formatting, whitespace (no logic) |77| `perf` | Performance improvement |78| `ci` | CI configuration |79| `build` | Build system / external deps |8081Examples:82```83feat(todos): add due-date filter dropdown (#42)8485fix(useTodos): handle null localStorage on initial load (#87)8687refactor(TodoItem): extract LabelList sub-component (#91)88```8990### Commit rules91- One logical change per commit. Not "fix stuff".92- Imperative mood: "add feature", not "added feature".93- No trailing period on the subject line.94- Reference the Issue with `(#NNN)` in the subject or `Closes #NNN` in the95 footer.96- Body explains WHAT and WHY, not HOW.9798## Change sizing99100| Size | Lines changed | Scope |101|------|---------------|-------|102| XS | 1–20 | Single function, config tweak |103| S | 20–50 | Small component change |104| M | 50–100 | One feature slice |105| L | 100–300 | Multi-file feature — consider splitting |106| XL | 300+ | Must split into multiple commits |107108**Rule of ~100:** aim for ~100 lines per commit. Larger diffs are harder to109review and more likely to contain bugs.110111## Atomic commits112113Each commit must:1141. Compile and pass tests (`git bisect`-friendly).1152. Contain one coherent change — not a WIP dump.1163. Be independently revertable.117118Squash temporary commits before merging.119120## PR discipline121122- PR title mirrors the lead commit's subject.123- PR description follows the project's template and includes:124 `Closes #NNN`, summary, screenshots if UI, test plan, rollback plan.125- Reviewers requested per CODEOWNERS or role.126- CI must be green before merge.127- Merge strategy: **squash** by default (one Issue → one commit on `main`).128 Use **merge commit** only when commits are already atomic and meaningful.129130## Push & PR authorization131132- Local commits: always fine.133- `git push`, `gh pr create`, `gh_*_create_pull_request`,134 `gh_*_merge_pull_request`: only with explicit user authorization for that135 action in the current session.136- If unsure, ask the user. Default to NOT pushing.137138## Common rationalisations139140| Rationalisation | Reality |141|---|---|142| "I'll clean up the commits later." | Later never arrives. Squash before opening a PR. |143| "This is just a small fix, no need for a branch." | Every change gets a branch. No exceptions. |144| "The commit message is obvious from the diff." | The diff shows WHAT, not WHY. The message captures intent. |145| "I'll push now and clean up after." | No. Pushing changes the contract with the team and triggers CI. |146147## Red flags148149- Commits titled "fix", "update", "stuff", "WIP".150- Branches with many authors or lasting more than a few days.151- Large diffs (300+ lines) in a single commit.152- Commits that don't compile or fail tests.153- Pushes that were not explicitly authorized.154155## Verification156157- [ ] Branch name follows `<type>/<issue#>-<slug>` convention.158- [ ] Commit messages follow Conventional Commits and reference the Issue.159- [ ] Each commit is < ~100 lines where possible.160- [ ] All commits compile and tests pass.161- [ ] Branch is rebased onto latest `main` before opening a PR.162- [ ] No push or PR action was taken without explicit user authorization.163164---165> Source: [mtel-thailand/ai-template](https://github.com/mtel-thailand/ai-template) — distributed by [TomeVault](https://tomevault.io).166<!-- tomevault:4.0:skill_md:2026-06-16 -->
tomevault-io