Adopt Beads issue tracking

.beads/.gitignore

@@ -0,0 +1,2 @@
+*.db
+*.db-*

AGENTS.md

@@ -1,20 +1,106 @@
 # Agent Instructions
 
+## Issue Tracking with Beads
+- Use the `bd` Beads CLI for all issue, task, and dependency tracking in this repository.
+- Initialize the tracker with `bd init` if the `.beads/` database is missing, and commit the resulting files.
+- When you discover new work, blockers, or follow-ups while coding, immediately create a Beads issue before continuing the task at hand.
+- Keep issue metadata accurate: set priorities, statuses, and dependency edges (`blocks`, `related`, `parent-child`, `discovered-from`) so the ready queue always reflects the next actionable work.
+- Review available work with `bd ready`/`bd list` at the start of each session, and close or update issues as soon as the underlying work lands.
+
 ## Documentation Workflow
-- After each batch of changes, add a `CHANGELOG.md` entry with an ISO 8601 date/time stamp in United States Eastern time (include the timezone code, e.g., `America/New_York` or `ET`) and developer-facing detail (files, modules, functions, variables, and rationale). Every commit should correspond to a fresh entry.
+- After each batch of changes, add a `CHANGELOG.md` entry with an ISO 8601 timestamp in United States Eastern time (e.g., `America/New_York`) summarising developer-facing details and rationale.
 - Maintain `README.md` as the canonical description of the project; update it whenever behaviour or workflows change. Archive older versions separately when requested.
-- Keep the `docs/` wiki and provisioning guides (`SETUP.md`, `ENVIRONMENT_NEEDS.md`) in sync with code updates; add or revise the
-  relevant page whenever features, modules, or workflows change.
-- After each iteration, refresh `ISSUES.md`, `SOT.md`, `PLAN.md`, `RECOMMENDATIONS.md`, `TODO.md`, and related documentation to stay in sync with the codebase.
-- Ensure `TODO.md` retains the `Completed`, `Priority Tasks`, and `Recommended Waiting for Approval Tasks` sections, moving finished items under `Completed` at the end of every turn.
-- Make every task in `TODO.md` atomic: each entry must describe a single, self-contained deliverable with enough detail to execute and verify without cross-referencing additional context.
+- Keep the `docs/` wiki and provisioning guides (`SETUP.md`, `ENVIRONMENT_NEEDS.md`) in sync with code updates; revise the relevant page whenever features, modules, or workflows change.
+- After each iteration, refresh `ISSUES.md`, `SOT.md`, `PLAN.md`, and `RECOMMENDATIONS.md` so they stay aligned with the current state of the codebase and Beads issue tracker.
 - Update `RESUME_NOTES.md` at the end of every turn so the next session starts with accurate context.
-- When beginning a turn, review `README.md`, `PROJECT.md`, `PLAN.md`, `RECOMMENDATIONS.md`, `ISSUES.md`, `SOT.md`, `ROADMAP.md`, `PLANNING_THOUGHTS.md`, and the `research/` wiki to harvest new actionable work. Maintain at least ten quantifiable, prioritised items in the `Priority Tasks` section of `TODO.md`, adding context or links when needed.
+- When beginning a turn, review `README.md`, `PROJECT.md`, `PLAN.md`, `RECOMMENDATIONS.md`, `ISSUES.md`, `SOT.md`, `ROADMAP.md`, `PLANNING_THOUGHTS.md`, the `research/` wiki, and the open Beads issues to harvest actionable work.
 - Keep `ROADMAP.md`, `PLANNING_THOUGHTS.md`, and the `research/` docs aligned with each iteration when new discoveries or decisions occur.
-- After completing any task, immediately update `TODO.md`, check for the next actionable item, and continue iterating until all unblocked `Priority Tasks` are exhausted for the session.
-- Continuously loop through planning and execution: finish a task, document it, surface new follow-ups, and resume implementation so long as environment blockers allow. If extra guidance would improve throughput, extend these instructions proactively.
+- Continuously loop through planning and execution: finish a task, document it, surface new follow-ups as Beads issues, and resume implementation while unblocked work remains.
 
 ## Style Guidelines
 - Use descriptive Markdown headings starting at level 1 for top-level documents.
 - Keep lines to 120 characters or fewer when practical.
 - Prefer bullet lists for enumerations instead of inline commas.
+
+## bd quickstart reference output
+```
+bd - Dependency-Aware Issue Tracker
+
+Issues chained together like beads.
+
+GETTING STARTED
+  bd init   Initialize bd in your project
+            Creates .beads/ directory with project-specific database
+            Auto-detects prefix from directory name (e.g., myapp-1, myapp-2)
+
+  bd init --prefix api   Initialize with custom prefix
+            Issues will be named: api-1, api-2, ...
+
+CREATING ISSUES
+  bd create "Fix login bug"
+  bd create "Add auth" -p 0 -t feature
+  bd create "Write tests" -d "Unit tests for auth" --assignee alice
+
+VIEWING ISSUES
+  bd list       List all issues
+  bd list --status open  List by status
+  bd list --priority 0  List by priority (0-4, 0=highest)
+  bd show bd-1       Show issue details
+
+MANAGING DEPENDENCIES
+  bd dep add bd-1 bd-2     Add dependency (bd-2 blocks bd-1)
+  bd dep tree bd-1  Visualize dependency tree
+  bd dep cycles      Detect circular dependencies
+
+DEPENDENCY TYPES
+  blocks  Task B must complete before task A
+  related  Soft connection, doesn't block progress
+  parent-child  Epic/subtask hierarchical relationship
+  discovered-from  Auto-created when AI discovers related work
+
+READY WORK
+  bd ready       Show issues ready to work on
+            Ready = status is 'open' AND no blocking dependencies
+            Perfect for agents to claim next work!
+
+UPDATING ISSUES
+  bd update bd-1 --status in_progress
+  bd update bd-1 --priority 0
+  bd update bd-1 --assignee bob
+
+CLOSING ISSUES
+  bd close bd-1
+  bd close bd-2 bd-3 --reason "Fixed in PR #42"
+
+DATABASE LOCATION
+  bd automatically discovers your database:
+    1. --db /path/to/db.db flag
+    2. $BEADS_DB environment variable
+    3. .beads/*.db in current directory or ancestors
+    4. ~/.beads/default.db as fallback
+
+AGENT INTEGRATION
+  bd is designed for AI-supervised workflows:
+    • Agents create issues when discovering new work
+    • bd ready shows unblocked work ready to claim
+    • Use --json flags for programmatic parsing
+    • Dependencies prevent agents from duplicating effort
+
+DATABASE EXTENSION
+  Applications can extend bd's SQLite database:
+    • Add your own tables (e.g., myapp_executions)
+    • Join with issues table for powerful queries
+    • See database extension docs for integration patterns:
+      https://github.com/steveyegge/beads/blob/main/EXTENDING.md
+
+GIT WORKFLOW (AUTO-SYNC)
+  bd automatically keeps git in sync:
+    • ✓ Export to JSONL after CRUD operations (5s debounce)
+    • ✓ Import from JSONL when newer than DB (after git pull)
+    • ✓ Works seamlessly across machines and team members
+    • No manual export/import needed!
+  Disable with: --no-auto-flush or --no-auto-import
+
+Ready to start!
+Run bd create "My first issue" to create your first issue.
+```

CHANGELOG.md

@@ -1,5 +1,14 @@
 # Changelog
 
+## [2025-10-20T04:12:44-04:00 (America/New_York)]
+### Added
+- Introduced `.beads/` project database and exported Beads issue JSONL by initializing bd and migrating existing TODO items.
+- Added `reference-docs/` snapshots of upstream Beads documentation (`Beads-*.md`) for local reference.
+
+### Changed
+- Rewrote `AGENTS.md` to mandate Beads-based workflow and appended the `bd quickstart` reference output; simplified `TODO.md` to delegate planning to bd.
+- Imported every task from the legacy `TODO.md` into the Beads tracker with appropriate open/closed status and added an `ISSUES.md` note pointing contributors to bd commands.
+
 ## [2025-10-16T20:39:06-04:00 (America/New_York)]
 ### Added
 - Added live integration coverage for Memgraph, Neo4j, and Redis via `meshmind/tests/test_integration_live.py` and configured

ISSUES.md

@@ -1,5 +1,8 @@
 # Issues Checklist
 
+> [!NOTE]
+> Issue and task tracking now lives in the Beads issue tracker (`bd`). Use `bd list`, `bd show <issue>`, and `bd ready` for the live source of truth; the checklists below remain as historical context.
+
 ## Blockers
 - [x] MeshMind client fails without the `mgclient` module; introduce lazy driver initialization or documented in-memory fallback.
 - [x] Register a default embedding encoder (OpenAI or sentence-transformers) during startup so extraction and hybrid search can run.
@@ -38,4 +41,4 @@
 - [x] Offer alternative storage backends (in-memory driver, SQLite, etc.) for easier local development.
 - [x] Provide an administrative dashboard or CLI commands for listing namespaces, counts, and maintenance statistics (CLI admin subcommands now expose predicates, telemetry, and graph checks).
 - [ ] Publish onboarding guides and troubleshooting FAQs for contributors.
-- [ ] Explore plugin registration for embeddings and retrieval strategies to reduce manual wiring.
+- [ ] Explore plugin registration for embeddings and retrieval strategies to reduce manual wiring.