branch-worker-protocol

name	branch-worker-protocol
description	Standard git branching and commit workflow for worker agents operating in isolated worktrees. Covers branch naming, commit conventions, domain boundary rules, self-check procedures, and task completion signaling. Automatically loaded by all worker agents.
user-invokable	false

Branch Worker Protocol

You are working in an isolated git worktree. Follow this protocol for every task.

1. Branch Naming Convention

<domain>/<task-id>-<short-description>

Examples:

• backend/task-001-product-reviews-api
• frontend/task-004-review-components
• tests/task-006-review-api-tests
• mobile/task-010-product-listing-screen

Rules:

• Lowercase, hyphens only (no spaces or underscores)
• Task ID must match the assigned task
• Description should be 2-5 words summarizing the work

2. Starting a Task

git checkout -b <branch-name>
git status  # Verify you are on the correct branch

Then immediately confirm to the team-lead:

Branch created: <branch-name>
Starting TASK-<ID>: <title>

3. Commit Convention

Use conventional commits. Commit each logical chunk — do NOT batch all changes into a single commit at the end.

<type>(<scope>): <description>

[optional body]

Task: TASK-<ID>

Types: feat, fix, test, refactor, docs, chore

Scopes: api, services, prisma, components, pages, hooks, styles, tests

Examples:

feat(api): add POST /api/products/[id]/reviews endpoint

Validates review body with Zod, persists via ReviewService,
returns created review with author info.

Task: TASK-003

test(api): add unit tests for review service

Tests create, list, and delete operations.
Covers validation errors and not-found cases.

Task: TASK-006

4. Domain Boundaries — Hard Rule

You may ONLY modify files within your assigned domain directories.

If you discover you need a file outside your domain:

1. STOP — do not edit the file
2. Report to team-lead: "Need change in <file-path> because <reason>"
3. Wait for team-lead to either make the change or reassign it

Common cross-domain needs:

• Shared types in src/types/ → team-lead owns these
• Package dependencies in package.json → team-lead owns this
• Config files (tsconfig.json, next.config.*) → team-lead owns these
• Flutter dependencies in pubspec.yaml → team-lead coordinates
• Native code (android/, ios/) → mobile-dev owns, but team-lead coordinates with backend if needed

5. Pre-Completion Self-Check

Memory Check (before self-check)

Before running self-checks, update your task status:

1. Read .serena/memories/ouroboros/tasks/registry.md — update your task status to review
2. If you made architectural decisions, append to .serena/memories/ouroboros/architecture/conventions.md

Run ALL of these before reporting task done. Use the appropriate check commands for your detected stack.

Web/TypeScript Projects

# 1. Verify only your domain files were changed
git diff --name-only main...HEAD

# 2. No uncommitted changes remain
git status

# 3. TypeScript compiles without errors
npx tsc --noEmit

# 4. Linting passes
npx next lint

# 5. Relevant tests pass (if applicable)
npx vitest run --reporter=verbose

Flutter/Dart Projects

# 1. Verify only your domain files were changed
git diff --name-only main...HEAD

# 2. No uncommitted changes remain
git status

# 3. Dart analysis passes
dart analyze

# 4. Format check
dart format --set-exit-if-changed lib/ test/

# 5. Flutter tests pass
flutter test --reporter=expanded

Python Projects

# 1. Verify only your domain files were changed
git diff --name-only main...HEAD

# 2. No uncommitted changes remain
git status

# 3. Type checking passes
mypy .

# 4. Linting passes
ruff check .

# 5. Relevant tests pass (if applicable)
pytest --tb=short

If any check fails, fix the issue and re-run before reporting done.

6. Task Completion Message

When all self-checks pass, report to team-lead:

DONE: TASK-<ID>
Branch: <branch-name>
Files changed:
- <path/to/file.ts> (new)
- <path/to/other.ts> (modified)
Summary: <1-3 sentences describing what was implemented>
Tests: <X passed / not applicable>

7. When Blocked

If you cannot proceed, report immediately:

BLOCKED: TASK-<ID>
Reason: <specific thing that is missing or broken>
Need from: <team-lead | specific teammate>

Do NOT try to work around blockers by modifying files outside your domain.

8. Merge Conflicts

If you encounter merge conflicts:

1. Do NOT resolve them yourself
2. Report to team-lead with the conflicting file paths
3. Wait for team-lead to coordinate resolution