Git Ops

On first invocation, read references/orchestrator.md and follow its welcome protocol.

Move code from Claude’s workspace to a git repository with proper branch management, commit structure, and PR descriptions. This is the bridge between “Claude built it” and “it’s in version control.”

/oc-git — Command Reference

When the user types /oc-git, display this menu:

GIT OPS COMMANDS
━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━

  WORKFLOW
  /oc-commit           Stage + commit with structured message
  /oc-pr               Generate PR description from commits/checkpoint
  /oc-push             Push branch to remote
  /oc-git-sync         Full workflow: branch (from convention) → commit → push → PR
  /oc-git-release      Tag a merged release + push the tag (closes the ledger)

  UTILITIES
  /checkpoint          Show checkpoint status

━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━━
  Type any command to begin. /oc-git to see this again.

Plain requests, not slash commands: “set up the repo” (clone and prepare the workspace, Phase 0), “git status” (branch, staged changes, remote state and diff since the last commit), and “show / set the git conventions” (branch and commit naming).

How This Skill Works

CLAUDE WORKSPACE                    GIT REPO
<workspace>/project/                github.com/user/project
                                    
  Built files          ──────►      Feature branch
  + checkpoint data    ──────►      Structured commits
  + audit report       ──────►      PR description

The typical flow:

1. Clone the user’s repo (or confirm it’s already cloned)
2. Create a feature branch following project conventions
3. Copy/move built files into the repo working tree
4. Stage each intended commit and run oc-bug-check; an enrolled Git hook verifies the exact staged candidate and its immutable PASS receipt at each commit
5. Make structured commits (one per logical unit)
6. Push the branch
7. Run the pre-PR gate: oc-docs-forge (PR docs packet) → oc-repo-ops (readiness check); docs edits the packet makes are committed (through the bug-check gate) and pushed before the readiness check
8. Generate a PR description from the checkpoint + commit log + docs packet

Phase 0: Repository Setup (“set up the repo”)

First Time

# Clone the repo
git clone <repo-url> <workspace>/<project-name>
cd <workspace>/<project-name>

# Verify remote
git remote -v

# Check default branch
git symbolic-ref refs/remotes/origin/HEAD | sed 's@^refs/remotes/origin/@@'

Returning (repo already cloned)

cd <workspace>/<project-name>
git fetch origin
git checkout main && git pull origin main

Authentication

Git operations require auth. Check in this order:

1. SSH key — ls ~/.ssh/id_* (preferred for push)
2. Git credential helper — git config credential.helper
3. GitHub token — check env GITHUB_TOKEN or GH_TOKEN
4. Ask the user — “I need git push access. Can you provide a GitHub token or set up SSH?”

Store auth method in the checkpoint so future sessions don’t re-ask.

Branch Naming Convention

Default Convention

<type>/<short-description>

Types:
  feat/     New feature
  fix/      Bug fix
  refactor/ Code restructure (no behavior change)
  chore/    Dependencies, config, tooling
  docs/     Documentation only
  test/     Test additions or fixes
  deploy/   Deployment-related changes

Examples:

• feat/storefront-checkout-module
• fix/auth-session-expiry
• chore/update-wrangler-config
• deploy/add-staging-workflow

Convention from Checkpoint

If an oc-app-architect checkpoint exists, derive the branch name from it:

• Sprint 1 build → feat/sprint-1-auth-flow
• Code audit fix → fix/audit-f001-rate-limiting
• Deploy setup → deploy/ci-cd-pipeline

Naming conventions (“show / set the git conventions”)

Set or view the project’s naming conventions:

# Store in project config
cat > .git-ops-config.json << 'EOF'
{
  "branch_prefix": "feat|fix|refactor|chore|docs|test|deploy",
  "commit_format": "conventional",
  "default_base": "main",
  "pr_template": true,
  "auto_lint_before_commit": true
}
EOF

Commit Structure (/oc-commit)

Conventional Commits

<type>(<scope>): <description>

[optional body]

[optional footer]

Commit Granularity

One commit per logical unit of work. Rules of thumb:

Auto-Commit from oc-app-architect Phase 6 Sprints

When oc-app-architect completes a Phase 6 sprint, oc-git-ops can auto-structure commits:

# Read the sprint contract for commit scoping
# Each contract deliverable becomes one commit
# Invoke /oc-bugcheck run for each staged group before committing;
# the enrolled Git hook verifies each exact candidate at the commit boundary.

# Example for Sprint 1: Auth
git add src/db/migrations/ src/db/schema.ts
git commit -m "feat(db): add users and sessions tables"

git add src/auth/ src/middleware/session.ts
git commit -m "feat(auth): implement WebAuthn passkey flow"

git add src/auth/__tests__/ tests/
git commit -m "test(auth): add unit + integration tests for passkey auth"

Pre-Commit Gate (auto-invokes oc-bug-check)

Stage the intended commit, then invoke oc-bug-check before git commit. This is the canonical pre-commit workflow — oc-git-ops does NOT run its own ad-hoc lint/type/test checks. Bug-check owns the seven-check suite (types, lint, tests, anti-patterns, secrets, build, deps) and decides PASS or FAIL.

Skill(skill="oc-bug-check", args="/oc-bugcheck run")

Read the bug-check result and .checkpoints/oc-bug-check.checkpoint.json for diagnostics and last-run history. The checkpoint does not authorize a commit. At the Git boundary, the enrolled hook verifies the immutable staged candidate and revalidates a matching PASS receipt beneath the Git common directory (oc-bug-check § Commit gate contract).

Mechanical commit enforcement requires Git enrollment. From a repository checkout, run node scripts/install-git-drivers.mjs --enroll --repo "$(git rev-parse --show-toplevel)"; packaged plugin users run /oc-enroll. Plugin installation alone does not enroll a repository: its SessionStart/Stop hooks provide state and suggestions, and Claude PreToolUse hooks do not authorize or deny commits.

Enrollment installs the Git pre-commit hook and copies the verifier and receipt library beneath the Git common directory. Later commits use that installed runtime. A foreign hook is preserved; required enrollment returns BLOCKED with the exact final-decision snippet for manual hook-manager integration. Validate the composed hook before claiming enforcement. Repository marker directories alone do not install the hook.

The hook finishes any authoring-repository mirror updates, snapshots the effective index with git write-tree, runs the declared policy checks on that immutable candidate, and writes and revalidates a create-once receipt. The receipt binds repository, candidate tree, policy/config, toolchain, verifier and check results. Missing tools, non-PASS checks, index changes or mismatched evidence block the commit. Each distinct staged group requires its own matching receipt. Local hooks can be deliberately disabled; protected CI must independently verify the received candidate.

PR Description (/oc-pr)

Auto-Generated from Context

Pull from all available sources to build a comprehensive PR description:

1. Commit log — git log main..HEAD --oneline
2. App-architect checkpoint — which roadmap tasks this covers, the Phase 6 sprint contract and evaluator scores
3. Code-auditor checkpoint — findings addressed, remaining issues
4. Docs-forge checkpoint — skill_state.pr_body_fragment (the ## Documentation section) and pr_comment_marker for the optional docs comment

PR Template

## Summary

[2-3 sentences: what this PR does and why]

**Linked ticket:** [TICKET-1234](ticket-url)

## Changes

[Auto-generated from commit messages, grouped by type]

### Features
- [feat commits]

### Fixes
- [fix commits]

### Other
- [remaining commits]

## Documentation

[Inserted verbatim from the oc-docs-forge checkpoint (`skill_state.pr_body_fragment`).
The oc-repo-ops gate fails closed if this section is missing. If no user-facing docs
changed, oc-docs-forge says so explicitly and explains why — silence is not a pass.]

## Testing

- [ ] Unit tests pass (`npm test`)
- [ ] Type check passes (`tsc --noEmit`)
- [ ] Manual testing completed
[If oc-app-architect Phase 6: "Evaluated by oc-app-architect evaluator: X.X/10 (sprint N)"]

## Audit Status

[If oc-code-auditor ran: "Pre-deploy audit: Grade [X], [N] findings ([M] addressed in this PR)"]
[If not: "No code audit run — consider `/oc-audit pre-deploy` before merging"]
[Pre-PR gate: "oc-docs-forge packet ✓ · oc-repo-ops verdict PASS" — from the gate checkpoints]

## Deployment Notes

[Any migration steps, env var additions, or config changes needed]
[Auto-detected from: new migration files, .env.example changes, wrangler.toml changes]

Refs: TICKET-1234

Pre-PR Gate (auto-invokes oc-docs-forge, then oc-repo-ops)

Before creating any PR, run the v1.8 quality-gate rail. This is the canonical pre-PR gate — oc-git-ops does NOT write its own docs packet or hygiene checks. Docs Forge owns the PR documentation packet; Repo Ops decides whether the repository is clean enough to open the PR.

Skill(skill="oc-docs-forge", args="/oc-docs pr")

Then read .checkpoints/oc-docs-forge.checkpoint.json and insert skill_state.pr_body_fragment (the ## Documentation section) into the PR body. If pr_comment_marker is set, post the docs comment after the PR opens.

Skill(skill="oc-repo-ops", args="/oc-repo verify")

Then run node scripts/lib/release-evidence.mjs --stage pr. It requires A’s canonical PASS receipt for the exact candidate tree plus C-contract Docs Forge (pr-docs-v1) and Repo Ops (pr-readiness-v1) PASS handoffs bound to the HEAD tree projection excluding .checkpoints/. A squash merge whose source content changes produces a different projection and cannot reuse the prior evidence.

Required order (from the oc-repo-ops Every-PR Gate): bug-check (already run before every commit, including any docs-packet commit) → docs-forge → repo-ops → PR.

Creating the PR

# If gh CLI is available
gh pr create --title "[type]: [description]" --body-file /tmp/pr-description.md

# If not, output the description for the user to paste
echo "PR description saved to: /tmp/pr-description.md"
echo "Create the PR manually and paste this description."

Full Sync Workflow (/oc-git-sync)

One command that runs the entire flow:

/oc-git-sync [description]

1. Detect context — read checkpoints for project, skill, and current state
2. Determine branch name — from checkpoint or description
3. Create branch — git checkout -b <branch>
4. Stage changes — intelligently stage (skip build artifacts, node_modules)
5. Run oc-bug-check gate — invoke Skill(skill="oc-bug-check", args="/oc-bugcheck run") after the last edit and before any commit. FAIL aborts the sync — surface the failing checks and stop. The user can /oc-bugcheck fix, address the failures and re-run /oc-git-sync, or bypass explicitly as described in the Pre-Commit Gate table.
6. Structure commits — group by logical unit. For each distinct staged group, rerun step 5 before committing; the enrolled Git hook verifies that group’s exact candidate and matching receipt. A PASS for one index tree does not cover other groups or later edits.
7. Push — git push -u origin <branch>
8. Generate PR docs packet — invoke Skill(skill="oc-docs-forge", args="/oc-docs pr") to produce the ## Documentation body fragment (and any README/product-doc edits that must travel with the change)
9. Commit the docs edits — if step 8 changed files, stage them, re-run the oc-bug-check gate (step 5), commit (docs: …), push, and re-run /oc-docs pr at most once more so the packet’s verified_for_sha is the new HEAD (if that run edits files again, stop and surface it rather than looping). Skip when step 8 changed no files.
10. Run oc-repo-ops gate — invoke Skill(skill="oc-repo-ops", args="/oc-repo verify"), then node scripts/lib/release-evidence.mjs --stage pr. FAIL aborts the sync before the PR is created — surface the blocking findings; the user can /oc-repo clean or fix and re-run.
11. Generate PR description — from all available context, inserting the docs packet’s ## Documentation fragment
12. Create PR — via gh CLI or output for manual creation

At each step, show progress. If any step needs user input, ask once and continue.

Post-Sync Handoff

After /oc-git-sync completes successfully, hand off per orchestrator §3 (“git-sync completes”). Deploying is a user decision, so confirm first:

• If an oc-deploy-ops config exists for this project, ask: “Changes pushed. Run the deploy audit and deploy to staging?” On yes, invoke Skill(skill="oc-deploy-ops", args="/oc-deploy audit"), then Skill(skill="oc-deploy-ops", args="/oc-deploy staging").
• If no oc-deploy-ops config exists, offer /oc-deploy init to set up deployment, or /oc-audit pre-deploy for a quality check.

Release Tagging (/oc-git-release)

oc-release-ops Phase 5 hands off “the merge / tag” to this skill. Until v1.8.3 there was nothing here to catch it: the command reference had no tag verb, so the tag half of that handoff had nowhere to land.

It showed. The 2026-08-26 ledger audit found thirteen shipped releases on /changelog and three tags in git — v1.0 through v1.7 all shipped untagged.

/oc-git-release <semver>

Preconditions

Refuse and explain, rather than tagging anyway, if:

• HEAD is not reachable from origin/main (a release tag on an unmerged branch is worse than no tag — it points at code nobody else has).
• The project’s release version does not equal <semver>. In the opchain.dev repo that is the lockstep catalog version in skills/*/SKILL.md; in another project it is every version location listed in .opchain/release.yaml (oc-release-ops multi-project mode). A tag that disagrees with the version is a second lie, not a fix.
• (opchain.dev repo only) release-seal.json is missing or names another catalog version. The seal is the reviewed baseline an eventual tag must inherit.
• A tag v<semver> already exists. Never move a published tag; cut the next patch instead. In opchain.dev, publish-mcp-registry.yml has already fired for the old one.

Steps

1. git fetch origin main --tags
2. Verify the preconditions above.
3. git tag -s v<semver> -m "release: v<semver> — <theme>" on the reviewed merge commit. This is a human gate: if the signing key is unavailable, stop rather than substituting an unsigned or agent-authored tag.
4. (opchain.dev repo only) node scripts/check-release-tag.mjs --local — verify the seal, exact tagged publisher-workflow and server.json payload digests, catalog, ancestry, and tag signature before a push can trigger the OIDC publisher. Elsewhere, git tag -v v<semver> checks the signature.
5. git push origin v<semver> — in opchain.dev this is what triggers .github/workflows/publish-mcp-registry.yml. An unpushed tag republishes nothing.
6. Record the tag in oc-git-ops.checkpoint.json under skill_state.release_reconciliation, the shape the v1.9.0 cut wrote:

{ "skill_state": { "release_reconciliation": {
  "release_pr": { "number": 477, "merge_sha": "…", "merged_at": "…" },
  "tag": { "name": "v1.9.0", "object_sha": "…", "peeled_commit": "…",
           "signing_fingerprint": "…", "local_gate": "PASS", "remote_gate": "PASS" }
} } }

7. (opchain.dev repo only) Verify with node scripts/check-release-tag.mjs (exit 0). This remote gate proves origin contains the same signed tag object, not merely a different tag that peels to the same commit. Elsewhere, git ls-remote --tags origin v<semver> confirms the push.

This verb is not the enforcement

Documenting a verb does not make it run — this file saying so is the same prose that failed for ten releases. The edge is held by scripts/deploy.mjs, which refuses a production deploy when the catalog version has moved somewhere no tag follows. /oc-git-release is what you run to satisfy that guard; the guard is what makes you run it.

Project Governance Awareness

If a GOVERNANCE.md file exists in the project root (generated by oc-app-architect or the project-governance skill), read it before committing. Respect:

• Naming conventions — file naming, branch naming overrides
• Directory structure — where new files should be placed
• Version tracking — which documents are master copies vs. working drafts
• Git strategy — branching model (if different from oc-git-ops defaults)

If governance conventions conflict with oc-git-ops defaults, governance wins — it’s project-specific, oc-git-ops defaults are generic.

Checkpoint Integration

The shared checkpoint schema, write rules and resume protocol live in references/checkpoint-protocol.md, bundled with this skill. This section adds only what is specific to oc-git-ops.

Checkpoint Location

{project-dir}/.checkpoints/oc-git-ops.checkpoint.json

When to Write

Post-Merge Update

Restamp merged_prs at sensible inflection points — after a review wave, when a release ships, or when a session ends — not once per merge. Where the project has the checkpoint CLI, the single update is below; otherwise edit .checkpoints/oc-git-ops.checkpoint.json directly (append to skill_state.merged_prs, set step and status, restamp updated_at):

node scripts/checkpoint.mjs update oc-git-ops \
  "--skill_state.merged_prs:json+={...}" \
  "--step=last-merge-#${PR_NUM}" \
  "--status=complete"

Each :json+= flag appends one object; repeat the flag to record several PRs. (Up to v1.9.0 this recipe was written +:json=, which the CLI parsed as a literal key named merged_prs+; the CLI now accepts either order and refuses a key that still carries an operator.) Without the CLI, edit skill_state.merged_prs directly.

Do not automate this per-merge. opchain.dev once ran a .github/workflows/checkpoint-after-merge.yml that opened a bot/checkpoint-stamp-<PR> PR on every merge to main. It was removed 2026-06-22: under branch protection the bot’s auto-merge could never satisfy required review, so each merge left a permanent open PR, and because every PR appended to the same merged_prs array they mutually conflicted. The data is reconstructable from git log, so a CI-gated PR per merge is pure cost. See Anti-pattern: don’t auto-stamp merged_prs per merge in the checkpoint protocol. Other skills’ checkpoints (oc-orchestrator, oc-app-architect, oc-ux-engineer, etc.) stay assistant-driven because their content is contextual.

context_primer Template

{
  "key_decisions": [
    "Repo: github.com/acme/acme-core",
    "Auth: SSH key",
    "Convention: conventional commits, feat/fix/chore prefixes",
    "Last push: feat/storefront-module → origin, 6 commits"
  ],
  "generated_files": [
    "pr-description.md"
  ]
}

Cross-Skill Reads

.gitignore Enforcement

When committing, always verify these are gitignored:

node_modules/
.env
.env.local
dist/
build/
.wrangler/
.git-ops-config.json   # Local oc-git-ops config

Do not gitignore .checkpoints/ by default — the checkpoint protocol tracks it in git unless the project’s protocol says otherwise, and oc-repo-ops enforces that policy at the pre-PR gate. Only ignore it when the project has explicitly opted out. That includes archived checkpoints: they rotate into the tracked .checkpoints/history/ directory, so there is no .bak pattern to ignore.

If .gitignore is missing entries, add them in a separate chore: update .gitignore commit before the feature commits.

PM-Tool MCP Integration (v1.3+)

When the user invokes any verb with a ticket id — /oc-git-sync TICKET-1234, /oc-commit --ticket PLAT-12, or pastes a Linear / Jira / GitHub Issues URL — oc-git-ops reads the ticket via the configured PM-MCP and uses it for branch, commit, and PR shape.

The runtime contract — concrete tool names, retry policy, idempotency markers, and the pm_deferred_actions[] schema — lives in oc-integrations-engineer/references/pm-mcp-protocol.md, in that skill (not bundled with this skill; install the full catalog, or oc-integrations-engineer alongside it). All MCP calls below honour that contract; this section says only how oc-git-ops shapes branch / commit / PR / state from the ticket.

/oc-git-sync TICKET-1234 flow

1. Resolve provider from .opchain/pm.yaml (or detect from id pattern / URL). Apply tool_overrides from pm.yaml before falling through to the registry in protocol §1.
2. Call the registry-resolved get_issue tool (Linear: mcp__claude_ai_Linear__get_issue; GitHub: mcp__mcp-server-github__issue_read; Jira: mcp__atlassian__jira_get_issue) to fetch title, description, labels, priority, status, assignee. Apply the retry policy from protocol §2.
3. Branch name — slug {type}/{id}-{title-kebab-truncated-50}, where type is derived from the ticket type / labels: feat, fix, chore, docs, refactor. Default feat if ambiguous. The ticket id is mandatory and must preserve the PM tool’s canonical casing in the branch name (for example, feat/TICKET-1234-runtime-pm-mcp-made-real or fix/PROJ-57-auth-session-expiry). Do not drop or rewrite the id: Linear / Jira / GitHub integrations auto-link PRs by detecting the ticket id in branch / PR metadata.
4. Commit message — first line: {type}({scope}): {title}. Body: short paragraph summarising the change; trailer Refs: TICKET-1234 (or Closes: if the ticket is in a “ready-to-close” state).
5. PR title + body — title begins with [TICKET-1234] followed by the concise change summary. Body is generated from the ticket description, the diff summary, the oc-docs-forge packet (the ## Documentation section), and the auditor / oc-bug-check report (if present). It includes a top-line **Linked ticket:** [TICKET-1234](url) and a plain-text Refs: TICKET-1234 footer so Linear can auto-link even if branch detection fails.
6. PR open — only after the pre-PR gate passes (oc-docs-forge packet present, oc-repo-ops verdict PASS — see Pre-PR Gate above). Then pre-write check via the list_comments tool (Linear) or issue_read (GitHub, comments inline) for marker <!-- opchain:oc-git-ops:pr-opened:#<pr-number> -->. If absent, call the registry-resolved add_comment tool (Linear: mcp__claude_ai_Linear__save_comment; GitHub: mcp__mcp-server-github__add_issue_comment) with body <!-- opchain:oc-git-ops:pr-opened:#<pr-number> -->\nPR opened: <url>. Then resolve the in_review state string from pm.yaml.states and call the transition tool (Linear / GitHub: save_issue / issue_write with state field; Jira: mcp__atlassian__jira_transition_issue).
7. PR merge (when oc-git-ops observes the merge or is invoked with /oc-git-sync --closed) — same pre-write check pattern with marker <!-- opchain:oc-git-ops:pr-merged:#<pr-number> -->; comment carries the merge SHA + commit subject; transition to done (resolved from pm.yaml.states).

/oc-commit enrichment

If a ticket id appears in the user’s prompt but no /oc-git-sync, just enrich the commit body with Refs: TICKET-1234 and stop — the comment + transition is /oc-git-sync territory. No MCP call is made by /oc-commit alone.

Multi-ticket commits

If the staged diff spans multiple tickets (e.g. user says “this closes PLAT-1 and PLAT-2”), use the first as the branch / PR primary and add a Refs: line per additional ticket. Comment on each via add_comment, each carrying its own ticket-scoped marker <!-- opchain:oc-git-ops:pr-opened:#<pr-number>:<ticket-id> --> so re-runs are idempotent per ticket.

/oc-git-sync --retry-pm flush

Invokes the protocol §4 flush against oc-git-ops.checkpoint.json pm_deferred_actions[]. Filter to skill: "oc-git-ops" and retriable: true. Surfaces flushed N / failed M.

Failure modes

• MCP unavailable / unconfigured → fall back to slug from the user’s prompt and generic commit message; never block the commit on PM-MCP. The PR still opens.
• Ticket id format unrecognised → treat as plain text in the user prompt; do not call MCP.
• add_comment retry-budget exhausted (transient) → defer per protocol §4 with retriable: true; user can /oc-git-sync --retry-pm later. The PR is unaffected.
• 403 (cross-team scope) → defer with retriable: false; surface the permission error; never auto-flush. The PR is unaffected.

Principles

1. One logical change per commit. Not one file per commit. Not one sprint per commit. The unit is “one thing a reviewer can understand in isolation.”
2. Branch names tell a story. feat/sprint-2-crud-api beats update-stuff.
3. PR descriptions are for future-you. Six months from now, this PR title + description should explain why this change exists without reading the code.
4. Never force-push main. Feature branches can be force-pushed (rebased). Main cannot.
5. Commits are cheap, reverts are cheaper. Small, atomic commits make rollbacks surgical.
6. Auth setup happens once. Store the method in checkpoint, never re-ask.