---
name: workspace-repo-commit-protocol
description: How to interact with /workspace/repo — the mission's checked-out codebase — and how to commit + push meaningful changes back.
when_to_use: You are a coder, committer, or any role that edits code. Pin this at turn start so you never lose orientation.
tags: [foundation, coding, git]
---

# Workspace repo + commit protocol

You are running inside a mission's team container. The clawhdf5/backend/whatever repository the mission targets is bind-mounted at **`/workspace/repo`**. That is the ONLY path where source-modifying edits belong.

## Ground rules

1. **`cd /workspace/repo` at the start of every substantive turn.** If you `pwd` and it isn't `/workspace/repo`, cd there first — your default CWD is the ZeroClaw agent workspace (`~/workspace`), which is scratch storage, not the codebase.
2. **All `file_read` / `file_write` / `shell` calls that touch source use paths under `/workspace/repo`.** Anything else is scratch — the mission will not persist it.
3. **Never write files outside `/workspace/repo` and expect them to survive** — the agent workspace resets, `/tmp` is per-container ephemeral.

## Commit protocol

When (and only when) you have a meaningful, tested change:

```
cd /workspace/repo
git status                              # sanity-check what you touched
git diff --stat                         # confirm scope matches the plan
git add -A
git commit -m "<INT-NN> <one-line title>

<one-paragraph rationale — WHY, not what>

Refs: INT-NN
"
git push
```

- **Commit message uses the mission's INT-XX marker** on the subject line — the mission's task-card parser (Slice 5) advances state on it.
- **One INT per commit** unless the change genuinely can't be split; split-when-in-doubt.
- **Never `--force`, never rewrite pushed history** without an explicit `HANDOFF: safe to force-push` from the reviewer.

## When NOT to commit

- Tests failing → fix or revert; never commit red.
- Reviewer emitted `REVIEW_BLOCK: INT-NN — <reason>` for the current item.
- The change is a WIP or exploratory — that lives in the agent's scratch workspace, not the repo.

## Emit the completion marker

After a successful push, on a line by itself:

```
COMPLETED: INT-NN
```

The mission loop advances on that marker. If you didn't push, don't emit it.