docs: improve agent instructions based on session review

.agent/AGENTS.md

@@ -36,13 +36,15 @@ If the script outputs "STOP - ON PROTECTED BRANCH", you MUST NOT proceed with ed
 
 > On `main`. Suggested branch: `{type}/{suggested-name}`
 >
-> 1. Create worktree for suggested branch (recommended for parallel sessions)
-> 2. Create branch with checkout (switches current directory's branch)
+> 1. Create worktree for suggested branch (recommended - enables parallel work)
+> 2. Create branch with checkout (only if single-session workflow preferred)
 > 3. Use different branch name
 > 4. Stay on `main` (docs-only acceptable, otherwise not recommended)
 
 3. **Do NOT proceed until user replies with 1, 2, 3, or 4**
 
+**Default choice**: Prefer option 1 (worktree) unless user has expressed preference for option 2. Worktrees prevent branch-switching conflicts across terminals and AI sessions.
+
 **When option 4 is acceptable**: Documentation-only changes (README, CHANGELOG, docs/), typo fixes, version bumps via release script.
 **When option 4 is NOT acceptable**: Any code changes, configuration files, scripts.
 4. If worktree (option 1): `~/.aidevops/agents/scripts/worktree-helper.sh add {type}/{name}`
@@ -54,6 +56,8 @@ If the script outputs "STOP - ON PROTECTED BRANCH", you MUST NOT proceed with ed
 **Self-verification**: Before ANY file operation, ask yourself:
 "Have I run pre-edit-check.sh in this session?" If unsure, run it NOW.
 
+**Tool-level enforcement**: Before calling Edit, Write, or Bash (with file-modifying commands), you MUST have already confirmed you're on a feature branch. If the check hasn't been run this session, run it NOW before proceeding.
+
 **Working in aidevops framework**: When modifying aidevops agents, you work in TWO locations:
 - **Source**: `~/Git/aidevops/.agent/` - THIS is the git repo, check branch HERE
 - **Deployed**: `~/.aidevops/agents/` - copy of source, not a git repo

.agent/workflows/pr.md

@@ -201,6 +201,40 @@
 **Overall**: CHANGES REQUESTED
 ```text
 
+## Loop Commands
+
+For iterative PR workflows that automatically retry until success:
+
+| Command | Purpose | Default Limit |
+|---------|---------|---------------|
+| `/pr-loop` | Iterate until PR approved/merged | 10 iterations |
+| `/preflight-loop` | Iterate until preflight passes | 5 iterations |
+
+### Timeout Recovery
+
+If a loop times out before completion:
+
+1. **Check current status**:
+   ```bash
+   gh pr view --json state,reviewDecision,statusCheckRollup
+   ```
+
+2. **Review what's pending** - usually one of:
+   - CI checks still running (wait and re-check)
+   - Review requested but not completed (ping reviewer)
+   - Failing checks that need manual intervention
+
+3. **Fix and continue** - address issues, then:
+   ```bash
+   # Re-run single review cycle
+   /pr review
+
+   # Or restart loop if multiple issues remain
+   /pr-loop
+   ```
+
+Loops are convenience wrappers - the manual `/pr review` workflow always works.
+
 ## Fork Workflow (Non-Owner Repositories)
 
 When working on a repository you don't own, use the fork workflow:

.agent/workflows/preflight.md

@@ -226,6 +226,49 @@ path/to/false-positive.txt
 .agent/scripts/version-manager.sh bump patch
 ```text
 
+## Worktree Awareness
+
+When running preflight in a worktree, checks run against the **worktree's files**, not the deployed `~/.aidevops/agents/` version. This means:
+
+- Pre-existing issues in the deployed version won't be fixed by worktree changes
+- Issues will only be resolved after merge and redeployment (`./setup.sh`)
+- Focus on issues introduced by your changes, not inherited technical debt
+
+## Pre-existing vs New Issues
+
+Preflight checks report ALL issues, including pre-existing ones. When the loop hits max iterations or you see many violations:
+
+### Identifying New vs Pre-existing Issues
+
+```bash
+# See what files you changed
+git diff main --name-only
+
+# Check issues only in your changed files
+shellcheck $(git diff main --name-only -- '*.sh')
+```
+
+### When to Proceed Despite Issues
+
+If all remaining issues are **pre-existing** (not introduced by your PR):
+
+1. Verify your changes don't add new violations
+2. Document pre-existing issues for future cleanup
+3. Proceed with PR creation
+4. Note in PR description: "Pre-existing issues not addressed in this PR"
+
+### When to Fix Issues
+
+Fix issues that are:
+- Introduced by your changes
+- In files you're already modifying
+- Quick wins (< 5 minutes to fix)
+
+Defer issues that are:
+- Pre-existing in untouched files
+- Require significant refactoring
+- Outside the scope of your PR
+
 ## Related Workflows
 
 - **Version bumping**: `workflows/version-bump.md`

.agent/workflows/worktree.md

@@ -423,6 +423,32 @@ git status  # Shows detached HEAD
 git checkout feature/auth
 ```
 
+### Worktree Deleted Mid-Session
+
+If a worktree directory is removed (e.g., PR closed, manual deletion, cleanup script):
+
+```bash
+# 1. Check if branch still exists locally
+git branch --list feature/my-feature
+
+# 2. If branch exists, recreate worktree
+worktree-helper.sh add feature/my-feature
+
+# 3. If branch was deleted remotely but you have local changes
+git fetch origin
+git checkout -b feature/my-feature origin/feature/my-feature 2>/dev/null || \
+  git checkout -b feature/my-feature
+worktree-helper.sh add feature/my-feature
+
+# 4. Restore uncommitted changes from stash (if any were saved)
+git stash list
+git stash pop
+```
+
+**Session continuity**: After recreating the worktree, use `session-rename_sync_branch` tool to re-sync the OpenCode session name with the branch.
+
+**Prevention**: Before closing a PR or deleting a branch, ensure no active sessions are using that worktree. Use `worktree-sessions.sh list` to check.
+
 ## Comparison: Worktrees vs Alternatives
 
 | Approach | Pros | Cons |