# Workflow

## Purpose

This document defines the standard repository workflow for humans and coding agents working in HoopScout v2 phase 0. It describes how repository work should be organized, executed, and closed without drifting into product architecture decisions.

## Branch Policy

- `main` is the stable branch.
- `develop` is the integration branch.
- Normal work happens on `feature/*` branches created from `develop`.
- `release/*` branches are for release stabilization.
- `hotfix/*` branches are for urgent production fixes.

## Protected Branch Rules

- Do not work directly on `main`.
- Do not work directly on `develop`.
- Do not rewrite history without explicit approval.
- Do not broaden task scope unnecessarily.

## Standard Task Flow

The normal workflow for a focused task is:

1. Checkout `develop`.
2. Pull or otherwise update local state.
3. Create a `feature/*` branch from `develop`.
4. Complete one focused task.
5. Commit the changes.
6. Merge the branch back into `develop`.
7. Delete the feature branch when appropriate.

If a remote fetch or pull is unavailable, continue using local branch state and state that clearly in task communication.

## Codex Task Discipline

Codex work in this repository should follow this structure:

1. Confirm branch strategy.
2. State the branch to use.
3. List the files to change.
4. Explain the design briefly.
5. Make the requested changes.
6. Update tests and docs when relevant.
7. Provide the commit message.
8. Confirm the merge target.
9. Stop.

## Scope Discipline

Each branch should solve one clear problem. Unrelated cleanup, opportunistic refactoring, or scope expansion should not be mixed into the same task unless explicitly approved.

## When To Use an Umbrella Branch

Umbrella branches should be rare. Use one only for a large coordinated effort that requires multiple related task branches to be integrated together before merging back into `develop`.

If an umbrella branch is used, document:
- why it exists
- the exact branch name
- which task branches merge into it
- when it is expected to merge back into `develop`

## Review and Closeout Expectations

Before closing a task:
- changed files should match the task scope
- docs should be updated if behavior changes
- tests should be updated if behavior changes
- the merge target should be explicit

## Machine Portability Note

Durable workflow instructions must live in the repository, not only in local Codex configuration. Shared behavior should be documented in tracked files so contributors can work consistently across different machines.

## Minimal Examples

Example feature branch flow:

```bash
git checkout develop
git pull
# if git pull fails, continue using local branch state and say so explicitly
git checkout -b feature/example-task
# make focused changes
git commit -m "docs: describe example task flow"
git checkout develop
git merge --no-ff feature/example-task
```

## Related Files

- `AGENTS.md`
- `docs/MACHINE_SETUP.md`
- `docs/TASK_TEMPLATE.md`