git-discipline

Files (1)

• SKILL.md

SKILL.md (first lines)

<!-- sage-metadata
cost-tier: haiku
activation: auto
tags: [git, branching, worktree, merge, discipline, parallel-sessions]
inputs: [initiative-slug, workflow-mode]
outputs: [initiative-branch, manifest-branch-record]
-->

# Git Discipline

One branch per initiative. Merge only when the user says so.

This capability is the **single source of truth** for branch naming,
creation, merging, worktrees, and cleanup. Workflows cite it — they
never restate its rules. If a workflow's text and this file disagree,
this file wins; flag the workflow as the defect.

## Branch vs worktree — the decision rule

These solve different problems; pick by how many sessions run at once:

- **Branch** isolates *history* — one initiative's commits don't
  interleave with the default branch. A branch is **sufficient for
  one session at a time** (sequential initiatives). This is the
  default (`isolation: branch` in `.sage/config.yaml`).
- **Worktree** isolates the *working tree* — its own directory on
  disk. A worktree is **required for simultaneous sessions**: two
  `claude` processes in one checkout share one working tree and one
  HEAD, so they clobber each other's files regardless of branch, and
  `git checkout -b` in one moves HEAD for the other. Branches cannot
  fix a working-tree race; only a directory-per-session can.

**The hard constraint.** A Claude session is bound to the directory
it was launched in and **cannot relocate itself** into a worktree it
creates. So the parallel path is always launch-time: create the
worktree *first*, then start a session *inside* it. The front door is
**`sage worktree <slug>`** (creates branch + worktree + copies the
gitignored runtime + prints the `cd … && claude` line). Opt in with
`isolation: worktree`; until then, sequential branch-in-place is
unchanged.

## Availability check

Activate only when `git rev-parse --git-dir` exits 0. On failure
(not a git repository): silently inactive — no error, no prompt, no
mention. Every workflow runs exactly as it would without this
capability. Never run any other `git` command before this check
passes.

## Branch naming

| Workflow | Branch |
|----------|--------|
| `/build` | `feat/<slug>` |
| `/fix` | `fix/<slug>` |
| `/architect` | `arch/<slug>` |
| `/build-x` | `feat/<slug>` or `fix/<slug>` — planner proposes from the task shape, user confirms |
| `/autoresearch` | `autoresearch/<slug>` (pre-existing discipline, unchanged by this capability) |

`<slug>` is the initiative's work-dir slug **without** the date
prefix: `.sage/work/20260612-payment-retry/` → `feat/payment-retry`.
The full dated slug remains the work-dir key. On a name collision
(the branch already exists), append `-2`, `-3`, … — and never reuse
an existing branch without the user's explicit choice (see
"Already on a branch" below).

The naming extends the project's conventional-commit convention
(feat, fix, chore, docs) to branch names.

## Worktree bounce (`isolation: worktree` in the main checkout)

Read `isolation:` from `.sage/config.yaml` (default `branch`). When
it is `worktree` AND the workflow is starting in the **main checkout**
(not a linked worktree — the test is `git rev-parse --git-dir` ==
`git rev-parse --git-common-dir`; equal → main checkout), do not
branch in place. Present a **guided menu** (never a hard refusal — a
lone sequential session must still be able to proceed):

- `[1]` **Set up an isolated worktree** (recommended for parallel) —
  run / instruct `sage worktree <slug>`; open a session in the new
  directory and continue there. This session stops here.
- `[2]` **Proceed here in the shared checkout (not isolated)** — fall
  back to the normal in-place branch flow below; record the choice in
  the initiative decision log.
- `[3]` **Sequential, this once** — same as `[2]`, noting
  `isolation: worktree` was overridden for this initiative.

When already running **in a linked worktree** (the user launched via
`sage worktree`), skip the bounce and branch/commit in place as usual
— the session is already isolated (merging: "Worktree sessions" below). With `isolation: branch` (default),
the bounce never fires.

In Claude Desktop, the same bounce is simpler: offer to start a new Desktop
session with a worktree for the initiative instead of `sage worktree`.

## Branch creation (propose-confirm)

At the workflow step that consumes this capability, when HEAD is on
the default branch with a clean tree:

1. **Propose** the branch name from the table above.
2. **Let the user confirm or rename.** Never create silently. In Desktop
   mode the proposal is one button question: create it (Recommended),
   rename it, or stay on the default branch (the decline, recorded below).
3. `git checkout -b <branch>`
4. **Record the actual branch name** in the initiative's manifest
   frontmatter: `branch: feat/payment-retry`. Resume matching reads
   this recorded field — never re-derives from names (see "Branch ↔
   work-dir mapping" below).

**Dirty tree at creation time:** stop and present three options —
stash and proceed, commit current changes first (the user writes or
approves the message), or abort the workflow. Never stash silently.

**Already on a branch** (HEAD on a non-default branch): ask whether
to (a) continue on it — the user may have prepared one — or
(b) create the initiative branch from the default branch. Record the
choice in the initiative decision log. In a worktree session (Claude
Desktop, `claude --worktree`) do not ask: see "Worktree sessions" below.

From xoai/sage, MIT.

More from xoai/sage