johno/beads
1
0
Fork 0
Code Issues Pull Requests Actions Packages Projects Releases Wiki Activity

Less prescriptive landing protocol + recommend AGENTS.md session-ending hygiene

Browse Source 
- 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
This commit is contained in:
Steve Yegge
2025-11-05 15:20:58 -08:00
parent 6e8b4b8f19
commit 8f90b1f890
2 changed files with 40 additions and 14 deletions
Download Patch File Download Diff File Expand all files Collapse all files

28
README.md
View File

@@ -165,6 +165,34 @@ bd update <issue-id> --status in_progress --json
bd close <issue-id> --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.**