| name | contribution-flow |
| description | Repository contribution workflow. Use for any code change that should become a commit — adding features, fixing bugs, refactoring, or any source modification. Drives the full Issue → Branch → PR → Merge process. |
Contribution Flow
Issue → Branch → PR → Merge workflow for any code change in this repo. Coding standards live in the project's development guidelines (e.g. AGENTS.md); this skill only covers the process.
Conventions
Shared vocabulary used throughout the flow below: <type> and <scope> placeholders in every step refer back here.
- Types:
feat | fix | docs | style | refactor | perf | test | build | ci | chore | revert
- Scopes: infer from the project's top-level module/directory structure (e.g.
core, api, ui).
- Subject: lowercase, imperative mood, no trailing period.
- Consistency: the
<type> must match across the Issue title, branch prefix, every commit, and the PR title. The <scope> is required on commits and the PR title, optional on the Issue title, and omitted from the branch name.
The flow
1. Open the Issue
Pick the appropriate issue template from .github/ISSUE_TEMPLATE/ — using a template is mandatory. Fill it into /tmp/issue-body.md, then:
gh issue create --title "<type>: ..." --label "<appropriate label>" --body-file /tmp/issue-body.md
Capture the returned number as <N>.
Skipping the Issue: only when the user explicitly asks. Proceed to Step 2 with a descriptive branch name and note the skip in the PR description.
2. Branch from fresh main
git checkout main && git pull --ff-only
git checkout -b <type>/<kebab-slug>
3. Implement
Follow the project's development guidelines.
4. Precheck
Must pass before any commit:
./scripts/precheck.sh
5. Commit
git commit -am "<type>(<scope>): <short description>
Refs #<N>"
Multiple commits are fine — they are squashed on merge.
6. Push & Open the PR
Fill in the PR template from .github/PULL_REQUEST_TEMPLATE.md into /tmp/pr-body.md — using the template is mandatory. Then:
git push -u origin HEAD
gh pr create --base main --title "<type>(<scope>): ..." --body-file /tmp/pr-body.md
Report the PR URL back to the user.
7. Iterate on review
Push additional commits to the same branch. Do not force-push once a reviewer has left feedback, unless the user explicitly requests it.
8. Merge
Only on explicit user instruction.
gh pr merge <N> --squash --delete-branch && \
git checkout main && git pull --ff-only && \
git fetch --prune
CI failures
Inspect logs with gh run view --log-failed.
