docs(agents): clarify branch lifecycle and worktree workflow (#344)

This commit is contained in:
Will Sarg 2026-02-16 09:37:28 -05:00 committed by GitHub
parent c842ece12c
commit f0373f2db1
No known key found for this signature in database
GPG key ID: B5690EEEBB952194

View file

@ -172,6 +172,27 @@ When uncertain, classify as higher risk.
- If stacked PR: declare `Depends on #...`.
- If replacing old PR: declare `Supersedes #...`.
### 6.3 Branch / Commit / PR Flow (Required)
All contributors (human or agent) must follow the same collaboration flow:
- Create and work from a non-`main` branch.
- Commit changes to that branch with clear, scoped commit messages.
- Open a PR to `main`; do not push directly to `main`.
- Wait for required checks and review outcomes before merging.
- Merge via PR controls (squash/rebase/merge as repository policy allows).
- Branch deletion after merge is optional; long-lived branches are allowed when intentionally maintained.
### 6.4 Worktree Workflow (Required for Multi-Track Agent Work)
Use Git worktrees to isolate concurrent agent/human tracks safely and predictably:
- Use one worktree per active branch/PR stream to avoid cross-task contamination.
- Keep each worktree on a single branch; do not mix unrelated edits in one worktree.
- Run validation commands inside the corresponding worktree before commit/PR.
- Name worktrees clearly by scope (for example: `wt/ci-hardening`, `wt/provider-fix`) and remove stale worktrees when no longer needed.
- PR checkpoint rules from section 6.3 still apply to worktree-based development.
### 6.1 Code Naming Contract (Required)
Apply these naming rules for all code changes unless a subsystem has a stronger existing pattern.
@ -237,6 +258,17 @@ cargo clippy --all-targets -- -D warnings
cargo test
```
Preferred local pre-PR validation path (recommended, not required):
```bash
./dev/ci.sh all
```
Notes:
- Local Docker-based CI is strongly recommended when Docker is available.
- Contributors are not blocked from opening a PR if local Docker CI is unavailable; in that case run the most relevant native checks and document what was run.
Additional expectations by change type:
- **Docs/template-only**: run markdown lint and relevant doc checks.