dotfiles/.config/opencode/skills/git-workflow/SKILL.md

name, description, permalink

name	description	permalink
git-workflow	Procedures for git commits, worktrees, branches, and GitHub PRs — load before any git operation	opencode-config/skills/git-workflow/skill

Git Commit Procedure

1. Run git status to see all untracked and modified files.
2. Run git diff (staged + unstaged) to review changes that will be committed.
3. Run git log --oneline -5 to see recent commit message style.
4. Draft a Conventional Commit message (feat:, fix:, chore:, refactor:, docs:, test:):
   • Focus on why, not what.
   • 1-2 sentences max.
   • Match the repository's existing style.
5. Check for secrets: do NOT commit .env, credentials, or key files.
6. The managed per-repo basic-memory project directory is <repo>/.memory/; do not edit managed .memory/* files directly. Older repo-local memory workflow artifacts (including .memory.legacy/ and legacy contents from prior workflows) are non-authoritative and should not be edited unless explicitly migrating historical content into basic-memory.
7. Stage relevant files: git add <files> (not blindly git add .).
8. Commit: git commit -m "<message>".
9. Run git status after commit to verify success.

Git Worktree Procedure

When to use worktrees:

• Always use a worktree for new feature work to keep main clean.
• One worktree per independent workstream. If implementing multiple unrelated features, create separate worktrees for each.

Deciding on worktree count:

• 1 worktree: Single feature, or 2 tightly-coupled features sharing state/files.
• 2+ worktrees: Features that touch different domains, have different risk profiles, or could ship independently. Each gets its own worktree, branch, and PR.

Creating a worktree for a new feature:

# From project root
mkdir -p .worktrees
git check-ignore -q .worktrees || { printf "Add .worktrees/ to .gitignore before continuing.\n"; exit 1; }
git worktree add .worktrees/<feature-name> -b <branch-name>

Before starting feature implementation in the new worktree:

• Verify .worktrees/ is the project-local location and ignored by git before creating or reusing worktrees.
• Run project-declared setup/config scripts if the worktree needs dependencies or generated files.
• Run a baseline verification (project-declared check/test/lint scripts) to confirm the branch is clean before making changes.
• If baseline verification fails, stop and diagnose the environment or branch state before coding.

Creating multiple worktrees for independent workstreams:

# From project root — create all worktrees upfront
git worktree add .worktrees/<workstream-1> -b feat/<workstream-1>
git worktree add .worktrees/<workstream-2> -b feat/<workstream-2>

Working in a worktree:

• All file edits, test runs, and dev server starts must use the worktree path.
• Example: workdir="/path/to/project/.worktrees/my-feature" for all bash commands.
• Each coder invocation must target a specific worktree — never mix worktrees in one coder dispatch.

After implementation and tests pass: choose one finish path

1. Merge locally
   • Merge <branch-name> into your tracked/current base branch, then remove the feature worktree.
   • If the branch is fully integrated and no longer needed, delete it.
2. Push and open PR
   • Push <branch-name> and create a PR to the base branch using the GitHub PR procedure below.
   • Keep the worktree until review/merge is complete, then remove the worktree and delete the merged branch.
3. Keep branch/worktree for later
   • Leave branch and worktree in place when work is paused or awaiting input.
   • Record the next step and expected resume point so cleanup is not forgotten.
4. Discard work (destructive)
   • Only for work you explicitly want to throw away.
   • Require typed confirmation before running destructive commands: Type exactly: DISCARD <branch-name>.
   • After confirmation, remove the worktree and force-delete the unmerged branch with git branch -D <branch-name>; this cannot be undone from git alone once commits are unreachable.

Example local-merge cleanup flow:

# From the primary working tree
git checkout <base-branch>
git merge <branch-name>
git worktree remove .worktrees/<feature-name>
git branch -d <branch-name>  # optional cleanup when fully merged

Completing multiple worktrees (independent PRs):

Complete and merge each worktree independently. If workstream-2 depends on workstream-1, merge workstream-1 first, then rebase workstream-2 before merging.

GitHub PR Procedure

Push and create PR:

# Push branch
git push -u origin <branch-name>

# Create PR with heredoc body
gh pr create --title "<title>" --body "$(cat <<'EOF'
## Summary
- <bullet 1>
- <bullet 2>

## Changes
- <file/area>: <what changed>

## Testing
- <how it was validated>
EOF
)"

Check CI status:

gh run list                    # List recent workflow runs
gh run view <run-id>           # View specific run details
gh pr checks <pr-number>       # Check statuses on a PR

Issue operations:

gh issue list                  # List open issues
gh issue view <number>         # View specific issue
gh issue comment <number> -b "<comment>"  # Add comment

Safety Rules

• Never git push --force to main/master unless the user explicitly confirms.
• Never skip hooks (--no-verify) unless the user explicitly requests it.
• Never git commit --amend unless: (1) explicitly requested OR pre-commit hook auto-modified files, (2) HEAD was created in this session, AND (3) commit has NOT been pushed to remote.
• If commit fails due to pre-commit hook, fix the issue and create a NEW commit.