Git Workflow

Always Load This Skill

Any time a chat mentions git, GitHub, branches, commits, pushes, pulls, PRs, issues, worktrees, merge conflicts, releases, changelog entries, or dirty workspace cleanup, read this skill before acting. Treat it as the source of truth for routing changes to the right remote and for preserving local work safely.

Repository and Memory Routing

This checkout commonly has two remotes:

• upstream → mifunedev/agro (public template/canonical upstream)
• origin → your fork of openharness (private/operator fork)

Before every commit or PR, inspect the changed paths and choose the remote explicitly. Do not assume origin is the public target.

Issue Titles

Format: <prefix>(<issue#>): <shortdesc>

<prefix> ∈ feat · bug · task · audit · skill · agent (matches .github/ISSUE_TEMPLATE/<prefix>.md)

Example: feat(#42): slack thread replies

Create issue first so <issue#> exists, then branch.

Branch Names

Format: <prefix>/<issue#>-<short-desc>

• <short-desc>: kebab-case, ≤5 words
• Base off default target branch (see below)

Example: feat/42-slack-thread-replies

Default Target Branch

Use first existing in repo:

1. development (preferred)
2. main (fallback)
3. master (fallback)

Detect via git show-ref --verify --quiet refs/heads/<name> (or remote refs/remotes/origin/<name>). PRs target this branch; new branches cut from it.

Git Authentication

Inside sandbox, run gh auth login && gh auth setup-git during onboarding. GitHub CLI installs credential helper — git push / git fetch use your GitHub token — no SSH keys required.

PR Titles

Format: FROM <source-branch> TO <target-branch> (literal)

Example: FROM feat/42-slack-thread-replies TO development

PR Bodies

• Link issue: Closes #<issue#> (or Fixes/Resolves) in the PR title or body
• Target default target branch (development → main → master, whichever exists)

Closes #N closes the issue on merge into development — the workflow does it, not GitHub. GitHub honors a closing trailer only on merge into the default branch. PRs here target development while the default branch is main, so GitHub records the trailer as a referenced timeline event and nothing else. Verified on #759 (whose closed event carries commit=none) and independently on #753 from PR #757. .github/workflows/close-issues-on-development.yml closes the gap: on a merged PR into development it parses the title and body for the nine closing keywords and closes each referenced issue as completed (#841).

The trailer is therefore load-bearing — write it on every PR. Close by hand only when the automation cannot see the merge (a direct push, a merge into another branch, a PR whose body carried no trailer, or a PR opened from a fork, which gets a read-only token):

gh issue close <N> --repo <owner/name> --comment "Merged in #<PR>."

Commit Messages

Format: <type>: <description> where <type> ∈ feat · fix · task · audit · skill

Changelog

Root CHANGELOG.md follows Keep a Changelog with SemVer versions and v-prefixed tags.

Every PR with user-visible impact MUST add entry under ## [Unreleased] heading, in same commit as change. Categories: ### Added · ### Changed · ### Fixed · ### Removed · ### Deprecated · ### Security.

Skip entries only for pure chores with no runtime or workflow effect (internal refactors, test-only changes, typo fixes). When in doubt, add entry.

Entry format: ONE sentence, imperative mood, ≤ 250 characters, link the PR or issue.

An entry states WHAT changed and its user-visible effect. Never why. Never alternatives considered. Never implementation detail.

### Added
- Slack thread replies in multi-channel mode ([#42](https://github.com/mifunedev/openharness/pull/42)).

Displaced detail has a destination — put it there, not in the entry:

Detail	Destination
Rationale, rejected alternatives	The PR body — the ([#N]) link is the pointer
Task/spec decisions	.agro/tasks/<slug>/prd.md
Architecture decisions	docs/rfcs/
Durable, generalized lessons	A minted probe under .agro/evals/probes/

BAD (real entry, 3,579 chars — a design doc wearing a bullet):

- Add `oh harness <list|install|status>` so installing an agent harness stops requiring a full image rebuild. Adding one of the four optional harnesses previously meant knowing that `harness.yaml` carries an `install:` section, …

GOOD (233 chars — same fact, rationale left to the PR):

- Add `oh harness <list|install|status>` to install optional harnesses into a running sandbox without a rebuild, persisting the choice to `install.<key>` for the next build ([#821](https://github.com/mifunedev/openharness/pull/821)).

Enforced by .agro/evals/probes/changelog-entry-length.sh (report-only) over ## [Unreleased].

Automatic branch-push releases use the matching ## [<VERSION>] - YYYY-MM-DD section when one already exists; otherwise they publish the current [Unreleased] body. Do not hand-edit a versioned section after its tag ships, except for a repo-wide reformat that changes no facts.

Worktrees

Path: .worktrees/<branch> at the root of the repository the branch belongs to. A project clone under projects/ keeps its own worktrees the same way, at projects/<owner>/<repo>/.worktrees/. Independent project clones (own .git, not harness branches) live under projects/<owner>/<repo>/. Both roots are fixed conventions, not settings — see .worktrees/AGENTS.md and projects/AGENTS.md.

WORKTREES_ROOT="$(bash .agro/scripts/oh-path worktrees --no-create 2>/dev/null || printf '%s' .worktrees)"
mkdir -p "$WORKTREES_ROOT"
git worktree add "$WORKTREES_ROOT/<branch>" <branch>                # existing branch
git worktree add -b <prefix>/<issue#>-<short-desc> \
  "$WORKTREES_ROOT/<prefix>/<issue#>-<short-desc>" $BASE            # new branch off $BASE

Example path: .worktrees/feat/42-slack-thread-replies

Cleanup: git worktree remove "$WORKTREES_ROOT/<branch>".

.worktrees/ and projects/ gitignored (see .gitignore); only .worktrees/AGENTS.md and projects/AGENTS.md tracked.

Stale worktree policy

Worktrees older than 30 days without a corresponding open PR may be removed via git worktree remove; corrupted worktree directories may be removed with rm -rf after confirming they are not valid git worktree list entries. The /audit harness skill flags stale-worktree candidates for review before cleanup.

Isolating in-flight work

When main checkout has unstaged changes you shouldn't commit in current PR, do not stash-and-switch-branches (risk of losing context). Instead:

1. Cut worktree off target base: git worktree add -b <new> "$WORKTREES_ROOT/<new>" $BASE.
2. Copy in-flight files into worktree: plain cp preserves main checkout's working tree untouched.
3. Commit in worktree. Main checkout stays exactly as-is.

Before discarding duplicated state from main checkout, verify byte-equivalence with committed branch:

for f in <changed-files>; do
  a=$(md5sum "$f" | awk '{print $1}')
  b=$(git show <branch>:"$f" | md5sum | awk '{print $1}')
  [ "$a" = "$b" ] && echo "same:  $f" || echo "DRIFT: $f"
done

Only after all files show same: run git restore / rm -f to clean main checkout.

Destructive git under the cc-safety-net guard

cc-safety-net denies inline destructive git — git reset --hard <ref>, git clean -f, git branch -D, git worktree remove --force, git push --force — in every mode (its built-in git rules are not allowlistable). In agent (hook-mediated) contexts you must route these through the file-invoked shim instead:

bash .agro/scripts/git-maintenance.sh reset-hard <ref>
bash .agro/scripts/git-maintenance.sh clean
bash .agro/scripts/git-maintenance.sh branch-delete <branch>
bash .agro/scripts/git-maintenance.sh worktree-remove <path>
bash .agro/scripts/git-maintenance.sh push-force <remote> <branch>   # uses --force-with-lease

Scope rule: only non-agent-mediated invocations — raw scheduler/tmux shell scripts that never spawn a provider — bypass the PreToolUse hooks. Agent-driven crons do not bypass them (cron-runtime.ts runs them as pi --continue / claude -p prompts, so their Bash passes through the guard), so those must use the shim too. This is a compatibility shim, not a security control — the same script-file gap is also an evasion route; Docker is the security boundary.

Catching Up Feature Branches

When an open feature branch falls behind development, prefer merging the target branch into the feature branch instead of rebasing it. This preserves the branch's published history, avoids force-push churn, and keeps integration-conflict resolution on the feature branch; the final squash merge keeps development free of the catch-up merge commit.

git fetch origin development
git checkout <feature-branch>              # or run inside its worktree
git merge origin/development               # resolve conflicts on the feature branch
git push origin <feature-branch>           # normal push; no --force-with-lease

After the merge, rerun the targeted checks and /ci-status//audit pr before marking the PR ready or merging it.

Use rebase/force-push only for deliberate history surgery (for example, before a branch has been shared, or when explicitly managing a stacked PR as described below).

Stacked PRs

When PR needs work from another open PR (e.g. feature depending on in-flight docs or infra changes), stack instead of waiting:

1. git fetch origin <parent-branch>
2. In worktree: git rebase origin/<parent-branch>. Resolve conflicts; tests may need re-running.
3. git push --force-with-lease
4. gh pr edit <pr#> --base <parent-branch>
5. gh pr edit <pr#> --title "FROM <branch> TO <parent-branch>"

When parent PR merges, GitHub auto-rebases stacked PR's base to parent's target (development). Do not force-push again after parent merges — let GitHub handle retarget.

Keep stacks shallow: one level routine, two levels rare, three levels means something wrong with sequencing.

Releases

Every push to main or master triggers .github/workflows/release.yml. The workflow checks out the exact event SHA and requires validation, boot-path lint, and eval probes to pass before it mutates a tag, GitHub Release, or package. Do not manually pre-create a release tag or release/<version> branch.

Versioning is SemVer: MAJOR.MINOR.PATCH, tagged vMAJOR.MINOR.PATCH. Root package.json holds the release version. The workflow reads that file and never derives a version from the clock, so cutting a release is a deliberate bump, not a side effect of pushing. A cut bumps root package.json and .agro/cli/package.json (with its package-lock.json) to the same value. version-parity.sh fails the build on that canonical drift. The retained shim at .agro/cli/legacy/ keeps its own version and an exact @mifune/agro pin that equals that shim version. The shim version does not have to match a later canonical version.

Creating refs/tags/v<version> is the atomic reservation. A retry reads the same version from the same commit, so it reuses a same-SHA draft, and a retry of an already-published same-SHA release is a successful no-op.

An unbumped push to main is a clean skip, not a failure. When the tag already exists on a different commit, the reserve step reports the version as already released, sets publishedNoop=true, and the image, CLI, and finalize jobs all skip. The run stays green. To publish again, bump the version.

The v prefix appears only in the git tag and the GitHub Release name. The step output, the GHCR image tags, and the concurrency group all stay bare (ghcr.io/mifunedev/openharness:0.1.0, ghcr.io/mifunedev/agro:0.1.0).

One release publishes the canonical npm package @mifune/agro (agro). The @mifune/openharness shim source remains at .agro/cli/legacy/ and already-published shim versions remain on the registry. The release path does not publish, wait for, or deprecate the shim. The same build still publishes the GHCR tags ghcr.io/mifunedev/openharness:<version>, :sha-<sha>, ghcr.io/mifunedev/agro:<version>, :sha-<sha>, verified to share one digest, plus latest on both repositories; and the release assets agro.js, oh.js, get-agro.sh, get-oh.sh. Publishing @mifune/agro needs npm rights for that name, and the GHCR package mifunedev/agro must be made public after its first push; neither is verifiable here. The compatibility SLA clock starts at the first public AGRO release.

The artifact sequence is:

main|master push → validate + boot-lint + eval → read version from package.json
                 → reserve v<version> tag + draft
                 → build once + boot smoke + agro/oh version smoke
                 → push openharness + agro <version> and sha-<full-SHA> GHCR tags
                 → verify one digest → canonical latest-by-digest on both
                 → publish/no-op @mifune/agro
                 → attach agro.js, oh.js, get-agro.sh, get-oh.sh
                 → publish GitHub Release

The mutable/latest branch is canonically main when it exists, otherwise master. A helper fetches both refs immediately before digest promotion, so a master run can never regress latest when main exists; stale canonical runs also skip it. GitHub make_latest repeats the same fresh canonical check and is always false for the noncanonical branch. The GitHub Release stays draft until immutable image and successful/no-op CLI publication finish. See /release for the fast-forward promotion, monitoring, and verification procedure.

After Push

If .claude/skills/ci-status/ exists, invoke /ci-status after every git push to confirm pipeline green before declaring work done. Push failing CI is not done.

Provider Portability

Provider-specific rule files are not loaded by every provider, so put active instructions in skills. If you discover a provider-specific workflow dependency hiding in a rules file, promote it to a skill and leave a short rule file that points to the skill.

Workflow

Let $BASE = default target branch (detected per rule above).

1. Create GitHub issue → record <issue#>
2. git checkout -b <prefix>/<issue#>-<short-desc> $BASE
3. Add CHANGELOG.md entry under ## [Unreleased] (see § Changelog) — unless change is pure chore
4. Commit with <type>: <description>
5. git push -u origin <branch> → then /ci-status (if skill exists)
6. gh pr create --base $BASE --title "FROM <branch> TO $BASE" --body "Closes #<issue#>"
7. After the merge, confirm the issue closed. The close-issues-on-development workflow closes it from the Closes #N trailer (see § PR Bodies). If the merge bypassed a PR into development, close it by hand: gh issue close <issue#> --repo <owner/name>