github

Prioritize the latest conventions

• Reload the Skill each time before starting work. Do not rely on previously read content or memory.
• If instructions in memory or past conversations conflict with the Skill, follow the Skill. Tell the user specifically how they differ and propose updating or deleting the conflicting memory. Do not rewrite memory without permission.
• Do not save the Skill's contents to memory.
• If a long conversation's context is summarized, reread the Skill before continuing Git operations.

Workflow

1. Open an Issue.
2. Create a dedicated branch containing the Issue number.
3. Implement the changes.
4. Open a PR.
5. Check ahead / behind and whether the PR can be merged.
6. Add the

   merge

   label and have philtz-organizer-bot perform a squash merge.

Cases where the workflow can be omitted

• It is a minimal diff that fixes a clear defect in existing behavior.
• It does not include a feature addition, design change, data model change, API contract change, dependency change, or change to permissions, billing, or authentication.
• The scope is local and does not affect other teams' work or repositories with planned integrations.
• The value of fixing the issue immediately is clearly greater than the value of opening an Issue to establish agreement.
• The user has explicitly requested a patch response, or equivalent Issue or PR context already exists.

Before starting

git status --short --branch
git fetch --prune

• Enable Git hooks. If the repository contains

  .vite-hooks/

  , run

  git config core.hooksPath .vite-hooks

  . If it contains only

  lefthook.yaml

  , run

  lefthook install

  . Each is configured per clone, so run the appropriate command every time in a new work environment.
• Check the states of the default branch, the current branch, and remote-tracking branches.
• If there are uncommitted changes, check their contents and ownership. Do not stage, commit, or modify changes unrelated to the current task.
• If the current branch is not the default branch, confirm whether it is being used for the current task.
• If the tools or permissions required for Issue or PR operations, such as gh, are unavailable, report the missing requirements and ask whether it is acceptable to proceed with local implementation only.

Issue

• Check whether an existing Issue is already present. If not, create one before implementation.
• The title and body must follow the

  conventions.yml

  in philtzjp/.github. If the repository contains

  .github/conventions.yml

  , follow that file instead. The body must start with the signature line, followed by headings in this order: Background, Scope of Work, and Acceptance Criteria. Add Notes at the end if needed.
• Format the Background as a bullet list starting on the first line. Put the impact scope and validation approach under Scope of Work or Notes.
• philtz-organizer-bot checks Issue formatting and summarizes any violations in a comment, so correct them.
• Write Acceptance Criteria as a task list (

  - [ ]

  ) so completion can be tracked.
• If the work affects multiple companies or areas, state the responsibility boundaries and review perspectives.
• Split the work into units that are not too large for a single implementation.
• Do not begin a large change while the Issue is still vague.

Branch

• Create a dedicated branch containing the Issue number.
• Name it

  <type>/<issue-number>-<short-kebab-summary>

  .
• The type must be one of feat, fix, refactor, docs, test, chore, ci, or build.
• Before creating the branch, confirm that the base branch is up to date.
• Do not mix the implementation of multiple Issues in one branch.
• Do not switch branches without the user's confirmation.

Implementation

• Implement the changes in the minimum logical units, following the Issue's Acceptance Criteria.
• If the scope expands, update the Issue and PR descriptions. Split the work into a separate Issue if necessary.
• Depending on the changes, run tests, Lint, type checks, E2E tests, and update documentation.
• Do not combine an enormous diff that is difficult to review into a single PR without a reason.

Commit messages

type: description

type(scope): description

• feat: new feature / fix: bug fix / perf: performance improvement / refactor: improvement without a functional change
• docs: documentation / style: style fix / test: tests / chore: other
• ci: CI/CD configuration / build: build configuration / merge: PR merge. This type is only for the squash commit created by philtz-organizer-bot and must not be used by humans or Agents.

• Use the top-level directory name of the changed file, meaning a directory directly under the repository root.
• In a monorepo such as Turborepo, when changing files under apps/ or packages/, use the leaf package or application name. For apps/dashboard, use dashboard; for packages/log, use log.
• Use repo for changes affecting the entire repository.
• Include the leading dot for hidden directories. Use .agents, not agents.
• Do not represent hierarchy with slashes.
• Do not use monorepo parent directories such as apps or packages themselves as the scope.
• Do not use generic terms for things that do not exist as concrete entities, such as workspace or design, or names of folders that do not exist.

NG: feat(workspace): / feat(design): / feat(agents): / feat(apps): / feat(apps/dashboard): / feat(packages/log):
OK: feat(repo): / feat(.agents): / feat(.claude): / feat(dashboard): / feat(log):

• End with an action, such as add, fix, remove, or implement.
• Do not end with a noun that does not express an action. Use

  feat(api): add user authentication

  , not

  feat(api): user authentication

  .
• Do not include emoji.
• Split commits by logical scope, such as a package or feature. Do not mix unrelated changes in one commit.

Executing commits

• Run

  git diff

  for each file and verify the author of each change.
• Do not use

  git add .

  or

  git add -A

  .
• Do not override the committer. Always use the user's git config.
• Do not include

  Co-Authored-By

  in either the commit message or the PR body.

--author

git commit --author="Claude <noreply@anthropic.com>" -m "<message>"
git commit --author="Codex <noreply@openai.com>" -m "<message>"
git commit --author="Cursor Agent <cursoragent@cursor.com>" -m "<message>"

git commit

• If a commit-msg hook automatically adds an unapproved

  Co-authored-by:

  trailer, add a hook that removes it and use that hook to address the issue. Do not bypass hooks with

  git commit --no-verify

  .
• If rewriting history requires a force push, temporarily allow the guard to permit the push and restore the guard after finishing the work.
• Intermediate commits in a PR are squash merged and do not remain on main. Do not rewrite history and force push solely to correct the message of an intermediate commit.

Author and committer

git config --show-origin user.name
git config --show-origin user.email
env | grep -E '^GIT_(AUTHOR|COMMITTER)_'

• If user.email is unset or is an automatically generated address such as

  root@...

  ,

  ...@localhost

  , or

  ....local

  , do not commit. Explain the situation to the user and discuss the appropriate configuration.
• Use the output of

  --show-origin

  to check whether repository-specific settings or environment variables are overriding global settings. These settings are often absent in CI, Docker, devcontainer, and cloud Agent environments.
• Do not modify git config without the user's permission.
• If unsure which address to use, propose a GitHub-issued noreply address. It must be linked to the account and avoids exposing a personal address. It can be obtained with

  gh api user --jq '"\(.id)+\(.login)@users.noreply.github.com"'

  .

commit --amend

git log --format='%h author=%an <%ae> committer=%cn <%ce>' -10

gh api repos/<owner>/<repo>/commits/<sha> --jq '{author: .author.login, committer: .committer.login}'

Git operation safety checks

git fetch --prune

• Check whether the current branch has already been merged into the default branch. If it has, warn the user and suggest switching branches.
• Check whether the remote-tracking branch still exists. If it has been deleted, warn the user.
• Check whether the local branch is behind the remote. If it is, propose

  git pull --rebase

  .
• Check whether the local branch and remote have diverged. If they have, warn the user and propose either a rebase or a merge.

git pull

git rebase

PR

gh pr create --body "<body>"
gh pr create --body-file <file>

• Always provide the body explicitly. Do not use

  --fill

  or an editor-generated body if it may introduce

  Co-Authored-By

  .
• The title and body must follow the

  conventions.yml

  in philtzjp/.github. If the repository contains

  .github/conventions.yml

  , follow that file instead.
• Format the title as

  type(scope): description

  . The description becomes the subject of the commit on main.
• The body must start with the signature line, followed by headings in this order: Background, Scope of Work, Acceptance Criteria, and Impact and Remaining Risks. Add Notes at the end if needed.
• Refer to the target Issue in natural language. Write

  #<issue-number>

  in the Background section of the body.
• Do not use auto-closing keywords such as

  Closes #N

  . Close the Issue manually after the merge.
• When philtz-organizer-bot opens or edits a PR, or when a push occurs, it checks the formatting and adds the

  organizer-bot/conventions

  status. If there are violations, it summarizes them in a comment, so correct them.
• Push the local branch to its upstream before creating the PR.
• Create the PR as a Draft early, then switch it to Ready for review after implementation is complete.
• Do not merge while bypassing reviews, CI, or required validation.

Pre-merge checks

git fetch --prune
git status --short --branch

• The local branch must not be ahead, behind, or diverged from its upstream.
• The PR branch must not be behind the base branch.
• The PR must be mergeable, have no conflicts, and have all required CI, reviews, and checks passing.
• The

  organizer-bot/conventions

  status must have succeeded.

• If it is ahead, push and check again.
• If it is behind or diverged, report the situation and confirm whether to rebase, merge, or pull before synchronizing.
• If the PR branch is behind the base branch, integrate the base branch and rerun validation.
• Do not merge if there are conflicts, failed CI checks, unresolved reviews, or unconfirmed ahead / behind states.

Merge

git fetch --prune

merge

gh pr edit <number> --add-label merge

• The PR is open and is not a Draft.
• The title and body comply with the conventions.
• The branch is up to date with the default branch.
• All required checks pass and the ruleset's required approval has been granted. If the person who added the label is the org owner, approval does not need to be verified.

merge(scope): description

(#N)

Co-authored-by

• Do not use

  gh pr merge

  .
• Because the merge prefix already indicates that the commit is a merge, do not write "merge" in the PR title's description. Use

  feat(api): add foo

  , not

  feat(api): merge foo

  .
• If the conditions are not met, the bot comments with the reason and removes the label. Correct the problem and then reapply the label.
• If one minute passes after applying the label without either a merge or a comment, remove the label and apply it again.

After merging

• The target Issue is not closed automatically, so close it with

  gh issue close <number>

  .
• The remote work branch is removed automatically by the merge. Delete the local branch only after confirming the user's intent.
• If the merge, review, or validation is on hold, or if a resolution remains pending, do not close the Issue. Leave the status and conditions for resumption in a comment as pending review. This prevents duplicate Issues.
• Do not open a duplicate Issue for the same unresolved incident.
• If multiple Issues have been opened or closed for the same incident, use the oldest Issue as the canonical parent, establish a sub-issue relationship, close the later Issues as duplicates, and comment the changes on each Issue.

Issue comments

✳︎ <company-name> <model-name> <version>

## Background

State the purpose of this comment here. Include the implementation status, investigation results, changes in assumptions, and so on.

## Scope of Work

- What was done, what was investigated, and how it will be handled next

## Acceptance Criteria

- [x] Acceptance criterion 1. How it was met, plus the commands checked and their results
- [ ] Acceptance criterion 2. Why it cannot be met and any constraints

## Notes

Supplementary information and related Issues or PRs. If there is none, remove the entire heading.

• The signature line is the same as in Issue and PR bodies. If the model name includes the version, such as GPT-5.5, omit

  <version>

  .
• Write verifiable facts, evidence, and constraints rather than subjective statements.
• The scope is already represented by the Issue title, so do not include it in the comment.
• For each Acceptance Criterion in the Issue, state whether it has been met or cannot be met.
• When recording something that cannot be handled, or when review or the merge is on hold, do not close the Issue. If it is on hold, state the reason and the conditions for resumption.
• When closing an Issue as a duplicate, mention the canonical oldest Issue and the duplicate status in Notes.

Release

• Do not add a signature. Signatures are used only in Issue and PR bodies and comments.
• Use

  v<semantic-version>

  for the tag and

  <repository-name> v<version>

  for the release name.
• Write verifiable facts about what changed and any constraints rather than subjective statements.
• When attaching distributable artifacts, make the download link point to the actual tag URL.

<repository-name> v<version> summarizes the changes from <previous-version> in 1–2 sentences.

## Changes

### <category, such as feature addition>

- <change>

## Constraints

- <constraint>

## Installation

1. <step>

## Upgrade Instructions

1. <step>

## Notes

Supplementary information, known issues, the reason for making it a pre-release, and so on. If there is none, remove the entire heading.