agent-git-workflow

---
name: agent-git-workflow
description: Standardizes git workflow for the AI agent in the sandbox devcontainer: work in agent/<task>-<yyyymmdd>, integrate via agent, never push to main/master, open PRs via GitHub CLI. Use when the user asks to create branches, push changes, open PRs, or follow this sandbox repo setup.
---

# Agent Git Workflow (Sandbox)

## Context

- Workspace lives in Docker volume at `/workspaces/work` (no host bind mounts).
- Container/volume names may vary per project (see `.devcontainer/docker-compose*.yml`).
- A local safety pre-push hook blocks pushes to `main`/`master` (anti-footgun, not a server guarantee). It is installed in the image and is locked down (system `core.hooksPath`).
- By default the sandbox has **sudo + Docker host access** (docker.sock). This is convenient but dangerous: Docker operations are potentially destructive.

## Quick start

1) Go to the target repo directory (usually under `/workspaces/work/<repo>`).
2) Create a task branch off `agent`:

```bash
agent-task-branch <task-slug>
```

3) Make changes, commit.
4) Optional: push current task branch for remote backup (recommended for long tasks / “in progress” safety):

```bash
git push -u origin HEAD
```

5) Merge your task branch back into `agent` and push `agent`:

```bash
agent-merge-to-agent
```

6) Open PR `agent` → `main` only when the user explicitly asks (see rules below):

```bash
agent-open-pr
```

## Rules

### Hard rules (do not violate)

- Never push directly to `main`/`master`. Changes land in `main` only via PR.
- Never **intentionally bypass** safety mechanisms (pre-push hook / blocks). Examples of forbidden bypasses:
  - `git push --no-verify ...`
  - `git -c core.hooksPath=/dev/null push ...`
  - changing `core.hooksPath`, deleting hooks, or rewriting the hook script.
- Never embed secrets/tokens in:
  - repo files (commits),
  - remote URLs,
  - logs/outputs.
- If a task *requires* bypassing protections, stop and ask the user for explicit confirmation and a concrete reason.
- If Docker access is enabled, never run destructive commands (`rm`, `prune`, `system prune`, volume/network removals) unless the user explicitly requests them.

### Conventions

- **Branch strategy (default)**:
  - `agent` is the long-lived integration branch for the agent.
  - task branches `agent/<task>-<yyyymmdd>` are created **from `agent`** and merged back into `agent` after testing.
  - dates are UTC (scripts use `date -u`).
- **Push strategy**:
  - pushing `agent/<task>-...` is optional and used for remote backup during work (in case the sandbox/volume breaks).
  - `agent-merge-to-agent` pushes `agent` (this is the normal “publish progress” step).
- PR flow: `agent` → `main` **only on explicit user instruction** (and `agent-open-pr` enforces: PR into `main/master` only from `agent`).
- Prefer PRs for all changes, even if branch protection is not enforced server-side.

## Pre-flight (common failure points)

- Ensure GitHub auth exists inside the container:
  - `gh auth status`
  - docs: `docs/auth-inside-container.md`
- Ensure bot identity is set (inside container):
  - `git config --global user.name ...`
  - `git config --global user.email ...`

## Available scripts / commands

- `agent-task-branch <task-slug>`: ensure local `agent` exists, then create/switch to `agent/<task>-<yyyymmdd>` from `agent`.
- `agent-merge-to-agent`: merge current task branch into `agent` and push `agent`.
- `agent-open-pr [base]`: open PR from current branch to base. PR `agent` → `main` is allowed **only on explicit user instruction** (policy rule).
- `agent-new-branch <task-slug>`: legacy helper (does not ensure base `agent`); prefer `agent-task-branch`.

## Operational workflow

1) Clone repos under `/workspaces/work/<repo>`.
2) Create a task branch from `agent`: `agent-task-branch <task>`.
3) Commit small, coherent chunks.
4) Optional remote backup push (during work): `git push -u origin HEAD`.
5) Merge into `agent` and push `agent`: `agent-merge-to-agent`.
6) Only if the user explicitly asked: open PR `agent` → `main`:
   - ensure you're on `agent`
   - run `agent-open-pr`

PR bodies should include:
   - what changed,
   - how to test.