diff --git a/.agent/AGENTS.md b/.agent/AGENTS.md index 894ed2c1f4..907ff0ea45 100644 --- a/.agent/AGENTS.md +++ b/.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 diff --git a/.agent/workflows/pr.md b/.agent/workflows/pr.md index 01a0193ee0..efb44eae21 100644 --- a/.agent/workflows/pr.md +++ b/.agent/workflows/pr.md @@ -201,6 +201,40 @@ The `/pr` command produces a structured report: **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: diff --git a/.agent/workflows/preflight.md b/.agent/workflows/preflight.md index f9835bc7d5..9d7c5d6f53 100644 --- a/.agent/workflows/preflight.md +++ b/.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` diff --git a/.agent/workflows/worktree.md b/.agent/workflows/worktree.md index ed7ccc20f9..433161f7bd 100644 --- a/.agent/workflows/worktree.md +++ b/.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 |