# Git Workflow — Branching Strategy and Rules

## Branch Hierarchy

```
feature_*  →  vibes  →  testing  →  master
 (work)     (agent)   (beta)     (stable)
```

### `master`
- **Purpose**: Stable, tested, production-ready code. What end-users run.
- **Who commits**: Human only. Agents **must not** commit or merge here without explicit human instruction.
- **Requirements**: All tests pass. Code reviewed and approved by human.

### `testing`
- **Purpose**: Beta-quality code. May contain bugs. Not guaranteed safe.
- **Who commits**: Human only. Agents **must not** commit or merge here without explicit human instruction.
- **Requirements**: Human has reviewed `vibes` and approved promotion.

### `vibes`
- **Purpose**: Agent integration branch. Completed features, bug fixes, and tasks land here for human review.
- **Who commits**: Agents merge completed feature branches here. Human reviews and either approves (promotes to `testing`) or rejects (sends agent back to feature branch).
- **Requirements**: Feature branch's tests pass. Feature branch work is complete per task scope.

### `feature_<slug>`
- **Purpose**: Isolated work branches for a single feature, bug fix, or task.
- **Who commits**: Agents and humans.
- **Naming**: `feature_` prefix followed by a short, git-safe slug describing the task (e.g., `feature_add_toast_notifications`, `fix_exit_node_lookup`).
- **Branch point**: Usually off `master`. If chaining tasks or building on unmerged work, branch off `vibes` or `testing` as appropriate.

## Commit Discipline

Agents must commit frequently, after each self-contained logical unit of work. **Do not batch all changes into a single commit.**

- Commit after each passing test, completed function, or logical change.
- Each commit should be small, focused, and meaningful on its own.
- Every commit must be traceable, reversible, and not break existing tests.
- Granular commits enable easy bisecting, clear history, and precise rollbacks.

## Commit Messages

Use conventional commit format:

```
<type>: <short description>

<optional body explaining why>
```

Types: `feat`, `fix`, `refactor`, `docs`, `style`, `test`, `chore`, `perf`, `ci`, `build`.

Messages must explain **what** changed and **why**. Avoid vague messages like "fix stuff" or "update code".

## Rebasing & Syncing

Before merging a feature branch into `vibes`:

1. Rebase the feature branch onto the latest state of its base branch (`master`, `vibes`, or `testing`).
2. Resolve any conflicts during rebase.
3. Verify tests still pass after rebase.

This keeps history linear and avoids unnecessary merge commits.

## Workflow

### Starting Work
1. Create a new `feature_<slug>` branch from the appropriate base branch (default: `master`).
2. Push the feature branch to remote.
3. Implement the feature, bug fix, or task.
4. Commit frequently (see Commit Discipline above).
5. Run tests after each commit. Ensure project-wide testing strategy passes.

### Completing Work (Agent)
1. Rebase feature branch onto latest base branch.
2. Merge the feature branch into `vibes` (preserve individual commits, do not squash).
3. Push `vibes` to remote.
4. Notify human that work is on `vibes` for review. **Stop and wait for human feedback.**

### Human Review
1. Human reviews `vibes` branch.
2. **If approved**: Human merges `vibes` → `testing`.
3. **If rejected**: Human communicates what needs fixing. Agent returns to the feature branch (or creates a new one) to address issues.

### Promoting to Stable
1. Human validates `testing` branch is ready.
2. Human merges `testing` → `master`.

## Agent Guardrails

- **NEVER** commit directly to `master` or `testing` without explicit human instruction.
- **NEVER** merge into `master` or `testing` without explicit human instruction.
- Always work in a `feature_<slug>` branch.
- Merge completed work to `vibes`, then stop and wait for human review.
- Preserve individual commits when merging — do not squash.
- Rebase feature branches before merging to `vibes` — do not create merge commits.

## Branch Management

- `feature_*` branches may be deleted after merging to `vibes` if no longer needed.
- If work is rejected from `vibes`, keep the feature branch for iterative fixes.
- `vibes` should be kept in a mergeable state — do not let it accumulate broken code.
- Push feature branches to remote for backup and visibility.

## Quick Spikes & Exploration

For quick local exploration or solo spikes, use `.scratch/<feature-slug>/` as documented in `docs/agents/repo-instructions.md`. When spike work becomes real, move it to a proper `feature_*` branch.