From 8f90b1f89060a2f06cf11b6c4395573a86415629 Mon Sep 17 00:00:00 2001 From: Steve Yegge Date: Wed, 5 Nov 2025 15:20:58 -0800 Subject: [PATCH] Less prescriptive landing protocol + recommend AGENTS.md session-ending hygiene - AGENTS.md: Updated 'landing the plane' section to encourage creative, methodical conflict resolution instead of rigid step-by-step commands - README.md: Added 'Configuring Your Own AGENTS.md' section recommending that project maintainers add session-ending protocols to their own AGENTS.md files to ensure proper database hygiene --- AGENTS.md | 26 ++++++++++++-------------- README.md | 28 ++++++++++++++++++++++++++++ 2 files changed, 40 insertions(+), 14 deletions(-) diff --git a/AGENTS.md b/AGENTS.md index ec2346c3..264ae139 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -607,12 +607,9 @@ bd sync --merge 1. **File beads issues for any remaining work** that needs follow-up 2. **Ensure all quality gates pass** (only if code changes were made) - run tests, linters, builds (file P0 issues if broken) 3. **Update beads issues** - close finished work, update status -4. **Git pull & rebase** -5. **bd sync** - verify both import and export succeeded -6. **Git push** - redo rebase if necessary until it succeeds -7. **Double-check for untracked files** (beads files often get dirty again after git push) -8. **Ensure no untracked files remain** -9. **Choose a follow-up issue for next session** +4. **Sync the issue tracker carefully** - Work methodically to ensure both local and remote issues merge safely. This may require pulling, handling conflicts (sometimes accepting remote changes and re-importing), syncing the database, and verifying consistency. Be creative and patient - the goal is clean reconciliation where no issues are lost. +5. **Verify clean state** - Ensure all changes are committed and pushed, no untracked files remain +6. **Choose a follow-up issue for next session** - Provide a prompt for the user to give to you in the next session - Format: "Continue work on bd-X: [issue title]. [Brief context about what's been done and what's next]" @@ -628,19 +625,20 @@ golangci-lint run ./... # 3. Close finished issues bd close bd-42 bd-43 --reason "Completed" --json -# 4. Pull & rebase +# 4. Sync carefully - example workflow (adapt as needed): git pull --rebase - -# 5. Sync beads -bd sync - -# 6. Push +# If conflicts in .beads/issues.jsonl, resolve thoughtfully: +# - git checkout --theirs .beads/issues.jsonl (accept remote) +# - bd import -i .beads/issues.jsonl (re-import) +# - Or manual merge, then import +bd sync # Export/import/verify git push +# Repeat pull/push if needed until clean -# 7-8. Verify clean state +# 5. Verify clean state git status -# 9. Choose next work +# 6. Choose next work bd ready --json bd show bd-44 --json ``` diff --git a/README.md b/README.md index 9db9c5b2..253f932b 100644 --- a/README.md +++ b/README.md @@ -165,6 +165,34 @@ bd update --status in_progress --json bd close --reason "Implemented" --json ``` +## Configuring Your Own AGENTS.md + +**Recommendation for project maintainers:** Add a session-ending protocol to your project's `AGENTS.md` file to ensure agents properly manage issue tracking and sync the database before finishing work. + +This pattern has proven invaluable for maintaining database hygiene and preventing lost work. Here's what to include (adapt for your workflow): + +**1. File/update issues for remaining work** +- Agents should proactively create issues for discovered bugs, TODOs, and follow-up tasks +- Close completed issues and update status for in-progress work + +**2. Run quality gates (if applicable)** +- Tests, linters, builds - only if code changes were made +- File P0 issues if builds are broken + +**3. Sync the issue tracker carefully** +- Work methodically to ensure local and remote issues merge safely +- Handle git conflicts thoughtfully (sometimes accepting remote and re-importing) +- Goal: clean reconciliation where no issues are lost + +**4. Verify clean state** +- All changes committed and pushed +- No untracked files remain + +**5. Choose next work** +- Provide a formatted prompt for the next session with context + +See the ["Landing the Plane"](AGENTS.md#landing-the-plane) section in this project's `AGENTS.md` for a complete example you can adapt. The key insight: explicitly reminding agents to maintain issue tracker hygiene prevents the common problem of agents creating issues during work but forgetting to sync them at session end. + ## The Magic: Distributed Database via Git Here's the crazy part: **bd acts like a centralized database, but it's actually distributed via git.**