---
name: workspace-repo-commit-protocol
description: How to work inside /mission/repo — the mission's checked-out codebase — and how to commit 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]
---

# Mission repo + commit protocol

The repository this mission targets is checked out at **`/mission/repo`**. That
is the only path where source-modifying edits belong.

## Ground rules

1. **`cd /mission/repo` at the start of every substantive turn.** If you `pwd`
   and it is somewhere else, cd there first.
2. **Every read and write that touches source uses a path under
   `/mission/repo`.** Anything else is scratch and will not be delivered.
3. On a mission with **no** repository, `/mission/repo` still exists and is
   writable — it is a scratch workspace, every file you leave there is
   collected when the phase ends and published as a mission artifact, and there
   is nothing to commit or push. Your task text says which kind of mission this
   is; believe it over any assumption.

## Use the tool names your prompt gives you

Your turn runs through Claude Code, so the tools are `Read`, `Edit`, `Write`,
`Bash`, `Glob`, `Grep`. Your prompt lists them explicitly — use those names.

Do not reach for `file_read`, `file_write`, `content_search` or `shell`. Those
are ZeroClaw's names, they are not what your subprocess exposes, and agents that
tried them spent whole turns describing the mismatch instead of working.

## Commit protocol

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

```
cd /mission/repo
git status                              # what did you actually touch
git diff --stat                         # does the scope match the plan
git add -A
git commit -m "<INT-NN> <one-line title>

<one paragraph on WHY, not what>

Refs: INT-NN
"
```

- **Put the INT-XX id on the subject line.** This is for the humans and for
  `git log --oneline` — nothing in the platform reads your commit messages.
  Mission state advances on the marker you emit **in your turn output**
  (`COMPLETED: INT-NN`, below), which is the only text the task-card parser
  reads. Committing with the id and never emitting the marker leaves the
  mission open on an item you have already finished.
- **One INT per commit** unless the change genuinely cannot be split. Split when
  in doubt: a commit covering three items cannot be reverted for one of them.
- **Never `--force`, never rewrite pushed history** without an explicit
  `HANDOFF: safe to force-push` from the reviewer.
- Push only if your task says to. Many missions deliver by having the platform
  diff your checkout, and a phase that pushes when it should not is harder to
  undo than one that did not push.

## When NOT to commit

- Tests failing. Fix or revert; never commit red.
- The reviewer emitted `REVIEW_BLOCK: INT-NN` for the current item.
- The change is exploratory. That is not what the mission branch is for.

## Emit the completion marker

After the work is genuinely done, on a line by itself:

```
COMPLETED: INT-NN
```

Exactly one INT id, no bold, no code fence — the parser takes the literal line
and rejects anything else. The mission loop advances on it, so emitting one you
cannot back up desynchronizes the mission from the repository.