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:

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

git push -u origin HEAD

5. Merge your task branch back into agent and push agent:

agent-merge-to-agent

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

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.