Merge branch 'feature/workflow-doc-phase-0' into develop

docs/WORKFLOW.md

@@ -1,33 +1,94 @@
 # Workflow
 
-## Branch policy
+## Purpose
 
-Protected branches:
+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.
-- main
-- develop
 
-Normal task flow:
+## Branch Policy
-1. checkout develop
-2. create feature/<task-name>
-3. implement the task
-4. commit changes
-5. merge feature branch into develop
-6. delete feature branch when appropriate
 
-## When to use an umbrella branch
+- `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.
 
-Use an umbrella branch only for a large coordinated effort that spans multiple dependent feature branches.
+## Protected Branch Rules
 
-If used, document:
+- 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
-- its exact name
+- the exact branch name
-- which child branches merge into it
+- which task branches merge into it
-- when it is expected to merge back into develop
+- when it is expected to merge back into `develop`
 
-## Task discipline
+## Review and Closeout Expectations
 
-Each task should:
+Before closing a task:
-- have one clear goal
+- changed files should match the task scope
-- have one task branch
+- docs should be updated if behavior changes
-- end with a commit and merge target confirmation
+- tests should be updated if behavior changes
-- not silently include unrelated cleanup
+- 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
+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`