oc-git-ops

# 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-ops — Command Reference

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

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

  WORKFLOW
  /oc-git-init         Clone repo + set up workspace for a project
  /git-branch       Create a feature branch from convention
  /oc-git-commit       Stage + commit with structured message
  /oc-git-pr           Generate PR description from commits/checkpoint
  /git-push         Push branch to remote
  /oc-git-sync         Full workflow: branch → commit → push → PR

  UTILITIES
  /oc-git-status       Show current branch, staged changes, remote state
  /git-diff         Show what's changed since last commit
  /oc-git-convention   Show/set naming conventions for this project
  /checkpoint       Show checkpoint status

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

---

## How This Skill Works

```
CLAUDE WORKSPACE                    GIT REPO
/home/claude/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. Make structured commits (one per logical unit)
5. Push the branch
6. Generate a PR description from the checkpoint + commit log

---

## Phase 0: Repository Setup (/oc-git-init)

### First Time

```bash
# Clone the repo
git clone <repo-url> /home/claude/<project-name>
cd /home/claude/<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)

```bash
cd /home/claude/<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/pintrack-substance-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`

### /oc-git-convention

Set or view the project's naming conventions:

```bash
# 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-git-commit)

### Conventional Commits

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

[optional body]

[optional footer]
```

| Type | When |
|---|---|
| `feat` | New feature for the user |
| `fix` | Bug fix |
| `refactor` | Code change that doesn't fix a bug or add a feature |
| `chore` | Tooling, deps, config |
| `docs` | Documentation |
| `test` | Adding or fixing tests |
| `ci` | CI/CD changes |
| `style` | Formatting (no logic change) |

### Commit Granularity

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

| Change Size | Commit Strategy |
|---|---|
| Single file fix | 1 commit |
| New component (file + test + styles) | 1 commit |
| New feature (multiple files) | 1 commit per layer: schema → API → frontend → tests |
| Full sprint | 3-6 commits following the build order |
| Config/tooling changes | 1 commit, separate from feature work |

### 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:

```bash
# Read the sprint contract for commit scoping
# Each contract deliverable becomes one commit

# 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)

**Before staging files or running `git commit`, invoke the oc-bug-check skill.**
This is the canonical pre-commit gate — 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")
```

Then read `.checkpoints/oc-bug-check.checkpoint.json` for the verdict.

| Verdict | Action |
|---|---|
| PASS | Proceed to `git add` + `git commit` |
| FAIL | **ABORT.** Surface the failing checks and offer the user `/oc-bugcheck fix` (auto-fix lint/format) or `/oc-bugcheck bypass` (logged override). Do NOT call `git commi