docs(agents): clarify branch lifecycle and worktree workflow (#344)
This commit is contained in:
parent
c842ece12c
commit
f0373f2db1
1 changed files with 53 additions and 21 deletions
32
AGENTS.md
32
AGENTS.md
|
|
@ -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.
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue