dms_tailscalectl/docs/agents/git-workflow.md

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.