hoopscout-v2/docs/WORKFLOW.md

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:

git checkout develop
git pull
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