diff --git a/AGENTS.md b/AGENTS.md index d912b39..725423e 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -22,27 +22,43 @@ the user explicitly says not to: 2. Make all edits inside the new worktree created for the task. 3. Run relevant validation. 4. Commit the changes with a Conventional Commit message. -5. Push the branch to GitHub. -6. Open a pull request with a Conventional Commit title. -7. Monitor the pull request until checks complete and it can merge cleanly. -8. Merge the pull request into `main`. -9. Confirm any required release has completed and any required container image or - other artifact has been published. -10. Remove the task worktree after the work has landed on `main` and all - required release or publishing steps are complete. This means the worktree - must be unregistered from Git and its folder must be deleted from the local - disk. - -Do not stop after local edits or after opening a pull request. A file-changing -task is not complete until the code is on `main`, required release and -publishing work is complete, the task worktree has been removed from Git, and -the task worktree folder has been deleted from the local disk, unless the user -explicitly asked for local-only changes. +5. Stop there unless the user explicitly asks to publish, share, open a pull + request, merge, release, or deploy the work. + +Do not push branches to GitHub, open pull requests, merge to `main`, wait for +GitHub Actions, publish releases, or delete the task worktree as part of the +default local implementation workflow. The default handoff is a committed local +branch/worktree that the user can inspect, run locally, amend, or ask to publish +later. + +When the user explicitly asks to publish local work, complete this checklist: + +1. Confirm the intended local branch/worktree and inspect `git status`. +2. Run relevant validation again if the local commit is stale or unvalidated. +3. Push the local branch to GitHub. +4. Open a pull request with a Conventional Commit title. +5. Monitor the pull request until checks complete and it can merge cleanly. +6. Merge the pull request into `main` when requested or when the user's publish + request clearly asks for a complete merge/release flow. +7. Confirm any required release has completed and any required container image + or other artifact has been published. +8. Remove the task worktree only after its changes have landed on `main`, all + required release or publishing steps are complete, and there is no + uncommitted user work in that worktree. If a pull request has errors, failing checks, or merge conflicts, fix the issue -in a new dedicated worktree and open a new pull request. Repeat this cycle until -all required code is merged into `main` and any required release or image -publication is complete. +in a new dedicated worktree and open a replacement pull request. Repeat this +cycle until all requested code is merged into `main` and any required release or +image publication is complete. + +Use this prompt when you want an agent to publish a local branch: + +```text +Please publish the local branch for this work. Push the branch to GitHub, open a +pull request with a Conventional Commit title, monitor the checks, and merge it +when it is green. Then confirm any required release or image publication and +clean up the task worktree. +``` ## Out-of-Scope Findings @@ -151,10 +167,15 @@ Rules for integration and end-to-end tests: ## Pull Requests -After finishing the local implementation for a task, commit the work, push it to -GitHub, create a pull request, monitor it, and merge it into `main` unless the -user explicitly asks not to. Always use Conventional Commit names for commits -and pull request titles so release automation can function correctly. +After finishing the local implementation for a task, commit the work locally +with a Conventional Commit message unless the user explicitly asks not to. Do +not push the branch, create a pull request, monitor checks, merge, release, or +deploy unless the user explicitly asks to publish or share the work. + +When the user asks to publish local work, push the branch to GitHub, create a +pull request, monitor it, and merge it into `main` if requested or if the prompt +clearly asks for the full publish flow. Always use Conventional Commit names for +commits and pull request titles so release automation can function correctly. Keep monitoring the pull request until all checks pass and the branch can merge without conflict. If checks fail, errors appear, or a merge conflict is detected, @@ -195,8 +216,9 @@ remains outstanding. ## Completion Cleanup -When work is complete, remove the dedicated task worktree. Every file-changing -task must finish with no leftover local worktree for that task. +When published work is complete, remove the dedicated task worktree. Local-only +tasks may keep their task worktree so the user can inspect, run, or amend the +local branch before publishing. Cleanup requires both of these outcomes: @@ -204,12 +226,13 @@ Cleanup requires both of these outcomes: `git worktree remove ` from the main repository. - The task worktree folder no longer exists on the local disk. -Do not leave completed task worktrees hanging around. A completed task that still +Do not leave published task worktrees hanging around. Published work that still has a registered Git worktree or an on-disk worktree folder is not actually finished. Only remove a worktree after its changes are committed, pushed, merged into `main`, released, and published as appropriate for the task, including -publication of new container images or other release artifacts where relevant. -Never delete a worktree that contains uncommitted user work or unreleased -changes. +publication of new container images or other release artifacts where relevant, +or when the user explicitly asks to discard a local-only worktree. Never delete +a worktree that contains uncommitted user work or unpublished changes unless the +user explicitly asks you to discard it.