From 3319a6b23382a654861aa7446bb6e10208d6d7c1 Mon Sep 17 00:00:00 2001 From: Anthony Merlo Date: Sat, 22 Aug 2026 22:31:27 +0100 Subject: [PATCH] bd init: initialize beads issue tracking --- .beads/config.yaml | 2 ++ .gitignore | 5 +++ AGENTS.md | 82 +++++++++++++++++++++++++++++++++++++++++++++- CLAUDE.md | 57 +++++++++++++++++++++++++++++++- 4 files changed, 144 insertions(+), 2 deletions(-) diff --git a/.beads/config.yaml b/.beads/config.yaml index 6b32a99..df0849b 100644 --- a/.beads/config.yaml +++ b/.beads/config.yaml @@ -64,3 +64,5 @@ # Secret keys (stored in this file but prefer env vars to avoid git exposure): # - linear.api_key → use LINEAR_API_KEY env var instead # - github.token → use GITHUB_TOKEN env var instead + +sync.remote: "git+https://git.darkmark.co.uk/amerlo/nutrition-mcp.git" \ No newline at end of file diff --git a/.gitignore b/.gitignore index 8aca33a..73a8aba 100644 --- a/.gitignore +++ b/.gitignore @@ -6,3 +6,8 @@ .env # IDE .idea/ + +# Beads / Dolt files (added by bd init) +.dolt/ +.beads-credential-key +.beads/proxieddb/ diff --git a/AGENTS.md b/AGENTS.md index 2038a0e..ec2a542 100644 --- a/AGENTS.md +++ b/AGENTS.md @@ -108,4 +108,84 @@ rm -f file # NOT: rm file 2. **Run quality gates** - `cargo build --release && cargo test` 3. **Close completed issues** - `bd close ...` 4. **PUSH** - `git add -A && git commit -m "..." && git push` -5. **Verify** - `git status` must show clean working tree \ No newline at end of file +5. **Verify** - `git status` must show clean working tree + + +## Beads Issue Tracker + +This project uses **bd (beads)** for issue tracking. Run `bd prime` to see full workflow context and commands. + +### Quick Reference + +```bash +bd ready # Find available work +bd show # View issue details +bd update --claim # Claim work +bd close # Complete work +``` + +### Rules + +- Use `bd` for ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists +- Run `bd prime` for detailed command reference and session close protocol +- Use `bd remember` for persistent knowledge — do NOT use MEMORY.md files + +**Architecture in one line:** issues live in a local Dolt DB; sync uses `refs/dolt/data` on your git remote; `.beads/issues.jsonl` is a passive export. See https://github.com/gastownhall/beads/blob/main/docs/SYNC_CONCEPTS.md for details and anti-patterns. + +## Agent Context Profiles + +The managed Beads block is task-tracking guidance, not permission to override repository, user, or orchestrator instructions. + +- **Conservative (default)**: Use `bd` for task tracking. Do not run git commits, git pushes, or Dolt remote sync unless explicitly asked. At handoff, report changed files, validation, and suggested next commands. +- **Minimal**: Keep tool instruction files as pointers to `bd prime`; use the same conservative git policy unless active instructions say otherwise. +- **Team-maintainer**: Only when the repository explicitly opts in, agents may close beads, run quality gates, commit, and push as part of session close. A current "do not commit" or "do not push" instruction still wins. + +## Session Completion + +This protocol applies when ending a Beads implementation workflow. It is subordinate to explicit user, repository, and orchestrator instructions. + +1. **File issues for remaining work** - Create beads for anything that needs follow-up +2. **Run quality gates** (if code changed) - Tests, linters, builds +3. **Update issue status** - Close finished work, update in-progress items +4. **Handle git/sync by active profile**: + ```bash + # Conservative/minimal/default: report status and proposed commands; wait for approval. + git status + + # Team-maintainer opt-in only, unless current instructions forbid it: + git pull --rebase + bd dolt push + git push + git status + ``` +5. **Hand off** - Summarize changes, validation, issue status, and any blocked sync/commit/push step + +**Critical rules:** +- Explicit user or orchestrator instructions override this Beads block. +- Do not commit or push without clear authority from the active profile or the current user request. +- If a required sync or push is blocked, stop and report the exact command and error. + + + +## Beads Issue Tracker + +Use Beads (`bd`) for durable task tracking in repositories that include it. Use the `beads` skill at `.agents/skills/beads/SKILL.md` (project install) or `~/.agents/skills/beads/SKILL.md` (global install) for Beads workflow guidance, then use the `bd` CLI for issue operations. + +### Quick Reference + +```bash +bd ready # Find available work +bd show # View issue details +bd update --claim # Claim work +bd close # Complete work +bd prime # Refresh Beads context +``` + +### Rules + +- Use `bd` for all task tracking; do not create markdown TODO lists. +- Run `bd prime` when Beads context is missing or stale. Codex 0.129.0+ can load Beads context automatically through native hooks; use `/hooks` to inspect or toggle them. +- Keep persistent project memory in Beads via `bd remember`; do not create ad hoc memory files. + +**Architecture in one line:** issues live in a local Dolt DB; sync uses `refs/dolt/data` on your git remote; `.beads/issues.jsonl` is a passive export. See https://github.com/gastownhall/beads/blob/main/docs/SYNC_CONCEPTS.md for details and anti-patterns. + diff --git a/CLAUDE.md b/CLAUDE.md index 2038a0e..7293575 100644 --- a/CLAUDE.md +++ b/CLAUDE.md @@ -108,4 +108,59 @@ rm -f file # NOT: rm file 2. **Run quality gates** - `cargo build --release && cargo test` 3. **Close completed issues** - `bd close ...` 4. **PUSH** - `git add -A && git commit -m "..." && git push` -5. **Verify** - `git status` must show clean working tree \ No newline at end of file +5. **Verify** - `git status` must show clean working tree + + +## Beads Issue Tracker + +This project uses **bd (beads)** for issue tracking. Run `bd prime` to see full workflow context and commands. + +### Quick Reference + +```bash +bd ready # Find available work +bd show # View issue details +bd update --claim # Claim work +bd close # Complete work +``` + +### Rules + +- Use `bd` for ALL task tracking — do NOT use TodoWrite, TaskCreate, or markdown TODO lists +- Run `bd prime` for detailed command reference and session close protocol +- Use `bd remember` for persistent knowledge — do NOT use MEMORY.md files + +**Architecture in one line:** issues live in a local Dolt DB; sync uses `refs/dolt/data` on your git remote; `.beads/issues.jsonl` is a passive export. See https://github.com/gastownhall/beads/blob/main/docs/SYNC_CONCEPTS.md for details and anti-patterns. + +## Agent Context Profiles + +The managed Beads block is task-tracking guidance, not permission to override repository, user, or orchestrator instructions. + +- **Conservative (default)**: Use `bd` for task tracking. Do not run git commits, git pushes, or Dolt remote sync unless explicitly asked. At handoff, report changed files, validation, and suggested next commands. +- **Minimal**: Keep tool instruction files as pointers to `bd prime`; use the same conservative git policy unless active instructions say otherwise. +- **Team-maintainer**: Only when the repository explicitly opts in, agents may close beads, run quality gates, commit, and push as part of session close. A current "do not commit" or "do not push" instruction still wins. + +## Session Completion + +This protocol applies when ending a Beads implementation workflow. It is subordinate to explicit user, repository, and orchestrator instructions. + +1. **File issues for remaining work** - Create beads for anything that needs follow-up +2. **Run quality gates** (if code changed) - Tests, linters, builds +3. **Update issue status** - Close finished work, update in-progress items +4. **Handle git/sync by active profile**: + ```bash + # Conservative/minimal/default: report status and proposed commands; wait for approval. + git status + + # Team-maintainer opt-in only, unless current instructions forbid it: + git pull --rebase + git push + git status + ``` +5. **Hand off** - Summarize changes, validation, issue status, and any blocked sync/commit/push step + +**Critical rules:** +- Explicit user or orchestrator instructions override this Beads block. +- Do not commit or push without clear authority from the active profile or the current user request. +- If a required sync or push is blocked, stop and report the exact command and error. +