From f37c3dce5ede12c0fd4267e9430a43ed2c218bf6 Mon Sep 17 00:00:00 2001
From: m3tam3re
Date: Sun, 1 Nov 2026 14:04:16 +0100
Subject: [PATCH] bd init: initialize beads issue tracking
---
.agents/skills/beads/SKILL.md | 80 +++++++++++++++
.agents/skills/beads/agents/openai.yaml | 4 +
.beads/.gitignore | 7 ++
.beads/config.yaml | 4 +
.beads/hooks/post-checkout | 59 +++++++++++
.beads/hooks/post-merge | 59 +++++++++++
.beads/hooks/pre-commit | 59 +++++++++++
.beads/hooks/pre-push | 59 +++++++++++
.beads/hooks/prepare-commit-msg | 59 +++++++++++
.claude/settings.json | 15 +++
.codex/config.toml | 2 +
.codex/hooks.json | 51 ++++++++++
.cursor/hooks.json | 20 ++++
.cursor/rules/beads.mdc | 67 +++++++++++++
.gitignore | 4 +
AGENTS.md | 128 ++++++++++++++++++++++++
CLAUDE.md | 77 ++++++++++++++
17 files changed, 754 insertions(+)
create mode 100644 .agents/skills/beads/SKILL.md
create mode 100644 .agents/skills/beads/agents/openai.yaml
create mode 100755 .beads/hooks/post-checkout
create mode 100755 .beads/hooks/post-merge
create mode 100755 .beads/hooks/pre-commit
create mode 100755 .beads/hooks/pre-push
create mode 100755 .beads/hooks/prepare-commit-msg
create mode 100644 .claude/settings.json
create mode 100644 .codex/config.toml
create mode 100644 .codex/hooks.json
create mode 100644 .cursor/hooks.json
create mode 100644 .cursor/rules/beads.mdc
create mode 100644 AGENTS.md
create mode 100644 CLAUDE.md
diff --git a/.agents/skills/beads/SKILL.md b/.agents/skills/beads/SKILL.md
new file mode 100644
index 0000000..a5a3344
--- /dev/null
+++ b/.agents/skills/beads/SKILL.md
@@ -0,0 +1,80 @@
+---
+name: beads
+description: Use when working in a repository that uses bd or Beads for durable project task tracking, issue dependencies, blocker management, multi-session handoff, or shared work memory. Trigger when the user asks to find ready work, claim or close tasks, create follow-up work, inspect blockers, recover project context, or choose between local planning and persistent project tracking.
+---
+
+# Beads
+
+Use Beads as the shared project task system. Local plans, scratch files, and personal memories are useful, but they are not the durable source of truth for project work.
+
+## First Step
+
+Run:
+
+```bash
+bd prime
+```
+
+If that prints nothing, check whether the repository has an active Beads workspace:
+
+```bash
+bd where
+```
+
+## Preferred Route
+
+Use the `bd` CLI when shell access is available. It is the most compact and direct Beads interface.
+
+## Core CLI Workflow
+
+1. Find work:
+
+```bash
+bd ready
+bd list --status=open
+bd list --status=in_progress
+```
+
+2. Inspect before editing:
+
+```bash
+bd show
+```
+
+3. Claim work atomically:
+
+```bash
+bd update --claim
+```
+
+4. Create durable follow-up work when implementation reveals new tasks:
+
+```bash
+bd create "Short title" --description="Why this exists and what needs to be done" --type=task --priority=2
+```
+
+5. Close completed work:
+
+```bash
+bd close --reason="Completed"
+```
+
+## What Belongs In Beads
+
+Use Beads for:
+
+- shared project tasks
+- blockers and dependencies
+- discovered follow-up work
+- work that must survive thread reset, compaction, or handoff
+- status that another person or agent should be able to resume
+
+Use agent-local planning tools only for the current turn's execution checklist. Do not treat them as shared project state.
+
+## Rules
+
+- Do not create markdown TODO files as the source of truth when Beads is available.
+- Do not use `bd edit`; it opens an interactive editor. Use `bd update` flags instead.
+- Prefer `--json` when parsing `bd` output programmatically.
+- If hooks are installed, `bd prime` may already be injected. Run it manually when context is missing.
+- Do not auto-close or mutate tasks unless the work is actually complete.
diff --git a/.agents/skills/beads/agents/openai.yaml b/.agents/skills/beads/agents/openai.yaml
new file mode 100644
index 0000000..09c3b8f
--- /dev/null
+++ b/.agents/skills/beads/agents/openai.yaml
@@ -0,0 +1,4 @@
+interface:
+ display_name: "Beads"
+ short_description: "Project task tracking with bd"
+ default_prompt: "Use $beads to inspect ready work and manage durable project tasks."
diff --git a/.beads/.gitignore b/.beads/.gitignore
index 304f708..72bdc08 100644
--- a/.beads/.gitignore
+++ b/.beads/.gitignore
@@ -68,3 +68,10 @@ bd.db
# They would override fork protection in .git/info/exclude.
# Config files (metadata.json, config.yaml) are tracked by git by default
# since no pattern above ignores them.
+
+# Added by bd (missing required patterns)
+*.gate.lock*
+last_pull
+proxieddb/
+dolt-server-config.yaml
+proxied_server_client_info.json
diff --git a/.beads/config.yaml b/.beads/config.yaml
index 11d56fd..c403138 100644
--- a/.beads/config.yaml
+++ b/.beads/config.yaml
@@ -1 +1,5 @@
no-git-ops: true
+sync:
+ remote: "git+ssh://gitea@code.m3ta.dev/m3tam3re/agent-lib.git"
+export:
+ auto: true
diff --git a/.beads/hooks/post-checkout b/.beads/hooks/post-checkout
new file mode 100755
index 0000000..9d53a6f
--- /dev/null
+++ b/.beads/hooks/post-checkout
@@ -0,0 +1,59 @@
+#!/usr/bin/env sh
+# --- BEGIN BEADS INTEGRATION v1.3.2 ---
+# This section is managed by beads. Do not remove these markers.
+if command -v bd >/dev/null 2>&1; then
+ export BD_GIT_HOOK=1
+ _bd_timeout=${BEADS_HOOK_TIMEOUT:-300}
+ case "$_bd_timeout" in
+ *[!0-9]*|'') _bd_timeout_invalid=1 ;;
+ *[1-9]*) _bd_timeout_invalid=0 ;;
+ *) _bd_timeout_invalid=1 ;;
+ esac
+ if [ "$_bd_timeout_invalid" -eq 1 ]; then
+ echo >&2 "beads: invalid BEADS_HOOK_TIMEOUT; using 300 seconds"
+ _bd_timeout=300
+ fi
+ _bd_timeout_backend=none
+ _bd_timeout_command=
+ for _bd_timeout_candidate in timeout gtimeout; do
+ if command -v "$_bd_timeout_candidate" >/dev/null 2>&1; then
+ if _bd_timeout_version="$("$_bd_timeout_candidate" --version 2>/dev/null)"; then
+ case "$_bd_timeout_version" in
+ "timeout (GNU coreutils) "*) _bd_timeout_command=$_bd_timeout_candidate; break ;;
+ esac
+ fi
+ fi
+ done
+ if [ -n "$_bd_timeout_command" ]; then
+ _bd_timeout_backend=coreutils
+ if "$_bd_timeout_command" -- "$_bd_timeout" bd hooks run post-checkout "$@"; then
+ _bd_exit=0
+ else
+ _bd_exit=$?
+ fi
+ elif command -v perl >/dev/null 2>&1; then
+ _bd_timeout_backend=perl
+ if perl -e 'alarm shift; exec @ARGV' -- "$_bd_timeout" bd hooks run post-checkout "$@"; then
+ _bd_exit=0
+ else
+ _bd_exit=$?
+ fi
+ else
+ echo >&2 "beads: hook 'post-checkout' running without timeout; install coreutils or perl to enable BEADS_HOOK_TIMEOUT"
+ if bd hooks run post-checkout "$@"; then
+ _bd_exit=0
+ else
+ _bd_exit=$?
+ fi
+ fi
+ if { [ "$_bd_timeout_backend" = coreutils ] && [ "$_bd_exit" -eq 124 ]; } || { [ "$_bd_timeout_backend" = perl ] && [ "$_bd_exit" -eq 142 ]; }; then
+ echo >&2 "beads: hook 'post-checkout' timed out after ${_bd_timeout}s — continuing without beads"
+ _bd_exit=0
+ fi
+ if [ "$_bd_exit" -eq 3 ]; then
+ echo >&2 "beads: database not initialized — skipping hook 'post-checkout'"
+ _bd_exit=0
+ fi
+ if [ "$_bd_exit" -ne 0 ]; then exit "$_bd_exit"; fi
+fi
+# --- END BEADS INTEGRATION v1.3.2 ---
diff --git a/.beads/hooks/post-merge b/.beads/hooks/post-merge
new file mode 100755
index 0000000..63f2260
--- /dev/null
+++ b/.beads/hooks/post-merge
@@ -0,0 +1,59 @@
+#!/usr/bin/env sh
+# --- BEGIN BEADS INTEGRATION v1.3.2 ---
+# This section is managed by beads. Do not remove these markers.
+if command -v bd >/dev/null 2>&1; then
+ export BD_GIT_HOOK=1
+ _bd_timeout=${BEADS_HOOK_TIMEOUT:-300}
+ case "$_bd_timeout" in
+ *[!0-9]*|'') _bd_timeout_invalid=1 ;;
+ *[1-9]*) _bd_timeout_invalid=0 ;;
+ *) _bd_timeout_invalid=1 ;;
+ esac
+ if [ "$_bd_timeout_invalid" -eq 1 ]; then
+ echo >&2 "beads: invalid BEADS_HOOK_TIMEOUT; using 300 seconds"
+ _bd_timeout=300
+ fi
+ _bd_timeout_backend=none
+ _bd_timeout_command=
+ for _bd_timeout_candidate in timeout gtimeout; do
+ if command -v "$_bd_timeout_candidate" >/dev/null 2>&1; then
+ if _bd_timeout_version="$("$_bd_timeout_candidate" --version 2>/dev/null)"; then
+ case "$_bd_timeout_version" in
+ "timeout (GNU coreutils) "*) _bd_timeout_command=$_bd_timeout_candidate; break ;;
+ esac
+ fi
+ fi
+ done
+ if [ -n "$_bd_timeout_command" ]; then
+ _bd_timeout_backend=coreutils
+ if "$_bd_timeout_command" -- "$_bd_timeout" bd hooks run post-merge "$@"; then
+ _bd_exit=0
+ else
+ _bd_exit=$?
+ fi
+ elif command -v perl >/dev/null 2>&1; then
+ _bd_timeout_backend=perl
+ if perl -e 'alarm shift; exec @ARGV' -- "$_bd_timeout" bd hooks run post-merge "$@"; then
+ _bd_exit=0
+ else
+ _bd_exit=$?
+ fi
+ else
+ echo >&2 "beads: hook 'post-merge' running without timeout; install coreutils or perl to enable BEADS_HOOK_TIMEOUT"
+ if bd hooks run post-merge "$@"; then
+ _bd_exit=0
+ else
+ _bd_exit=$?
+ fi
+ fi
+ if { [ "$_bd_timeout_backend" = coreutils ] && [ "$_bd_exit" -eq 124 ]; } || { [ "$_bd_timeout_backend" = perl ] && [ "$_bd_exit" -eq 142 ]; }; then
+ echo >&2 "beads: hook 'post-merge' timed out after ${_bd_timeout}s — continuing without beads"
+ _bd_exit=0
+ fi
+ if [ "$_bd_exit" -eq 3 ]; then
+ echo >&2 "beads: database not initialized — skipping hook 'post-merge'"
+ _bd_exit=0
+ fi
+ if [ "$_bd_exit" -ne 0 ]; then exit "$_bd_exit"; fi
+fi
+# --- END BEADS INTEGRATION v1.3.2 ---
diff --git a/.beads/hooks/pre-commit b/.beads/hooks/pre-commit
new file mode 100755
index 0000000..0928485
--- /dev/null
+++ b/.beads/hooks/pre-commit
@@ -0,0 +1,59 @@
+#!/usr/bin/env sh
+# --- BEGIN BEADS INTEGRATION v1.3.2 ---
+# This section is managed by beads. Do not remove these markers.
+if command -v bd >/dev/null 2>&1; then
+ export BD_GIT_HOOK=1
+ _bd_timeout=${BEADS_HOOK_TIMEOUT:-300}
+ case "$_bd_timeout" in
+ *[!0-9]*|'') _bd_timeout_invalid=1 ;;
+ *[1-9]*) _bd_timeout_invalid=0 ;;
+ *) _bd_timeout_invalid=1 ;;
+ esac
+ if [ "$_bd_timeout_invalid" -eq 1 ]; then
+ echo >&2 "beads: invalid BEADS_HOOK_TIMEOUT; using 300 seconds"
+ _bd_timeout=300
+ fi
+ _bd_timeout_backend=none
+ _bd_timeout_command=
+ for _bd_timeout_candidate in timeout gtimeout; do
+ if command -v "$_bd_timeout_candidate" >/dev/null 2>&1; then
+ if _bd_timeout_version="$("$_bd_timeout_candidate" --version 2>/dev/null)"; then
+ case "$_bd_timeout_version" in
+ "timeout (GNU coreutils) "*) _bd_timeout_command=$_bd_timeout_candidate; break ;;
+ esac
+ fi
+ fi
+ done
+ if [ -n "$_bd_timeout_command" ]; then
+ _bd_timeout_backend=coreutils
+ if "$_bd_timeout_command" -- "$_bd_timeout" bd hooks run pre-commit "$@"; then
+ _bd_exit=0
+ else
+ _bd_exit=$?
+ fi
+ elif command -v perl >/dev/null 2>&1; then
+ _bd_timeout_backend=perl
+ if perl -e 'alarm shift; exec @ARGV' -- "$_bd_timeout" bd hooks run pre-commit "$@"; then
+ _bd_exit=0
+ else
+ _bd_exit=$?
+ fi
+ else
+ echo >&2 "beads: hook 'pre-commit' running without timeout; install coreutils or perl to enable BEADS_HOOK_TIMEOUT"
+ if bd hooks run pre-commit "$@"; then
+ _bd_exit=0
+ else
+ _bd_exit=$?
+ fi
+ fi
+ if { [ "$_bd_timeout_backend" = coreutils ] && [ "$_bd_exit" -eq 124 ]; } || { [ "$_bd_timeout_backend" = perl ] && [ "$_bd_exit" -eq 142 ]; }; then
+ echo >&2 "beads: hook 'pre-commit' timed out after ${_bd_timeout}s — continuing without beads"
+ _bd_exit=0
+ fi
+ if [ "$_bd_exit" -eq 3 ]; then
+ echo >&2 "beads: database not initialized — skipping hook 'pre-commit'"
+ _bd_exit=0
+ fi
+ if [ "$_bd_exit" -ne 0 ]; then exit "$_bd_exit"; fi
+fi
+# --- END BEADS INTEGRATION v1.3.2 ---
diff --git a/.beads/hooks/pre-push b/.beads/hooks/pre-push
new file mode 100755
index 0000000..24796d1
--- /dev/null
+++ b/.beads/hooks/pre-push
@@ -0,0 +1,59 @@
+#!/usr/bin/env sh
+# --- BEGIN BEADS INTEGRATION v1.3.2 ---
+# This section is managed by beads. Do not remove these markers.
+if command -v bd >/dev/null 2>&1; then
+ export BD_GIT_HOOK=1
+ _bd_timeout=${BEADS_HOOK_TIMEOUT:-300}
+ case "$_bd_timeout" in
+ *[!0-9]*|'') _bd_timeout_invalid=1 ;;
+ *[1-9]*) _bd_timeout_invalid=0 ;;
+ *) _bd_timeout_invalid=1 ;;
+ esac
+ if [ "$_bd_timeout_invalid" -eq 1 ]; then
+ echo >&2 "beads: invalid BEADS_HOOK_TIMEOUT; using 300 seconds"
+ _bd_timeout=300
+ fi
+ _bd_timeout_backend=none
+ _bd_timeout_command=
+ for _bd_timeout_candidate in timeout gtimeout; do
+ if command -v "$_bd_timeout_candidate" >/dev/null 2>&1; then
+ if _bd_timeout_version="$("$_bd_timeout_candidate" --version 2>/dev/null)"; then
+ case "$_bd_timeout_version" in
+ "timeout (GNU coreutils) "*) _bd_timeout_command=$_bd_timeout_candidate; break ;;
+ esac
+ fi
+ fi
+ done
+ if [ -n "$_bd_timeout_command" ]; then
+ _bd_timeout_backend=coreutils
+ if "$_bd_timeout_command" -- "$_bd_timeout" bd hooks run pre-push "$@"; then
+ _bd_exit=0
+ else
+ _bd_exit=$?
+ fi
+ elif command -v perl >/dev/null 2>&1; then
+ _bd_timeout_backend=perl
+ if perl -e 'alarm shift; exec @ARGV' -- "$_bd_timeout" bd hooks run pre-push "$@"; then
+ _bd_exit=0
+ else
+ _bd_exit=$?
+ fi
+ else
+ echo >&2 "beads: hook 'pre-push' running without timeout; install coreutils or perl to enable BEADS_HOOK_TIMEOUT"
+ if bd hooks run pre-push "$@"; then
+ _bd_exit=0
+ else
+ _bd_exit=$?
+ fi
+ fi
+ if { [ "$_bd_timeout_backend" = coreutils ] && [ "$_bd_exit" -eq 124 ]; } || { [ "$_bd_timeout_backend" = perl ] && [ "$_bd_exit" -eq 142 ]; }; then
+ echo >&2 "beads: hook 'pre-push' timed out after ${_bd_timeout}s — continuing without beads"
+ _bd_exit=0
+ fi
+ if [ "$_bd_exit" -eq 3 ]; then
+ echo >&2 "beads: database not initialized — skipping hook 'pre-push'"
+ _bd_exit=0
+ fi
+ if [ "$_bd_exit" -ne 0 ]; then exit "$_bd_exit"; fi
+fi
+# --- END BEADS INTEGRATION v1.3.2 ---
diff --git a/.beads/hooks/prepare-commit-msg b/.beads/hooks/prepare-commit-msg
new file mode 100755
index 0000000..6c9e95b
--- /dev/null
+++ b/.beads/hooks/prepare-commit-msg
@@ -0,0 +1,59 @@
+#!/usr/bin/env sh
+# --- BEGIN BEADS INTEGRATION v1.3.2 ---
+# This section is managed by beads. Do not remove these markers.
+if command -v bd >/dev/null 2>&1; then
+ export BD_GIT_HOOK=1
+ _bd_timeout=${BEADS_HOOK_TIMEOUT:-300}
+ case "$_bd_timeout" in
+ *[!0-9]*|'') _bd_timeout_invalid=1 ;;
+ *[1-9]*) _bd_timeout_invalid=0 ;;
+ *) _bd_timeout_invalid=1 ;;
+ esac
+ if [ "$_bd_timeout_invalid" -eq 1 ]; then
+ echo >&2 "beads: invalid BEADS_HOOK_TIMEOUT; using 300 seconds"
+ _bd_timeout=300
+ fi
+ _bd_timeout_backend=none
+ _bd_timeout_command=
+ for _bd_timeout_candidate in timeout gtimeout; do
+ if command -v "$_bd_timeout_candidate" >/dev/null 2>&1; then
+ if _bd_timeout_version="$("$_bd_timeout_candidate" --version 2>/dev/null)"; then
+ case "$_bd_timeout_version" in
+ "timeout (GNU coreutils) "*) _bd_timeout_command=$_bd_timeout_candidate; break ;;
+ esac
+ fi
+ fi
+ done
+ if [ -n "$_bd_timeout_command" ]; then
+ _bd_timeout_backend=coreutils
+ if "$_bd_timeout_command" -- "$_bd_timeout" bd hooks run prepare-commit-msg "$@"; then
+ _bd_exit=0
+ else
+ _bd_exit=$?
+ fi
+ elif command -v perl >/dev/null 2>&1; then
+ _bd_timeout_backend=perl
+ if perl -e 'alarm shift; exec @ARGV' -- "$_bd_timeout" bd hooks run prepare-commit-msg "$@"; then
+ _bd_exit=0
+ else
+ _bd_exit=$?
+ fi
+ else
+ echo >&2 "beads: hook 'prepare-commit-msg' running without timeout; install coreutils or perl to enable BEADS_HOOK_TIMEOUT"
+ if bd hooks run prepare-commit-msg "$@"; then
+ _bd_exit=0
+ else
+ _bd_exit=$?
+ fi
+ fi
+ if { [ "$_bd_timeout_backend" = coreutils ] && [ "$_bd_exit" -eq 124 ]; } || { [ "$_bd_timeout_backend" = perl ] && [ "$_bd_exit" -eq 142 ]; }; then
+ echo >&2 "beads: hook 'prepare-commit-msg' timed out after ${_bd_timeout}s — continuing without beads"
+ _bd_exit=0
+ fi
+ if [ "$_bd_exit" -eq 3 ]; then
+ echo >&2 "beads: database not initialized — skipping hook 'prepare-commit-msg'"
+ _bd_exit=0
+ fi
+ if [ "$_bd_exit" -ne 0 ]; then exit "$_bd_exit"; fi
+fi
+# --- END BEADS INTEGRATION v1.3.2 ---
diff --git a/.claude/settings.json b/.claude/settings.json
new file mode 100644
index 0000000..8487f87
--- /dev/null
+++ b/.claude/settings.json
@@ -0,0 +1,15 @@
+{
+ "hooks": {
+ "SessionStart": [
+ {
+ "hooks": [
+ {
+ "command": "bd prime --hook-json",
+ "type": "command"
+ }
+ ],
+ "matcher": ""
+ }
+ ]
+ }
+}
diff --git a/.codex/config.toml b/.codex/config.toml
new file mode 100644
index 0000000..146af7e
--- /dev/null
+++ b/.codex/config.toml
@@ -0,0 +1,2 @@
+[features]
+hooks = true
diff --git a/.codex/hooks.json b/.codex/hooks.json
new file mode 100644
index 0000000..13c7229
--- /dev/null
+++ b/.codex/hooks.json
@@ -0,0 +1,51 @@
+{
+ "hooks": {
+ "PostCompact": [
+ {
+ "hooks": [
+ {
+ "command": "bd codex-hook PostCompact",
+ "statusMessage": "Scheduling Beads context refresh",
+ "type": "command"
+ }
+ ],
+ "matcher": "manual|auto"
+ }
+ ],
+ "PreCompact": [
+ {
+ "hooks": [
+ {
+ "command": "bd codex-hook PreCompact",
+ "statusMessage": "Checking Beads context",
+ "type": "command"
+ }
+ ],
+ "matcher": "manual|auto"
+ }
+ ],
+ "SessionStart": [
+ {
+ "hooks": [
+ {
+ "command": "bd codex-hook SessionStart",
+ "statusMessage": "Loading Beads context",
+ "type": "command"
+ }
+ ],
+ "matcher": "startup|resume|clear"
+ }
+ ],
+ "UserPromptSubmit": [
+ {
+ "hooks": [
+ {
+ "command": "bd codex-hook UserPromptSubmit",
+ "statusMessage": "Refreshing Beads context",
+ "type": "command"
+ }
+ ]
+ }
+ ]
+ }
+}
diff --git a/.cursor/hooks.json b/.cursor/hooks.json
new file mode 100644
index 0000000..9d731c8
--- /dev/null
+++ b/.cursor/hooks.json
@@ -0,0 +1,20 @@
+{
+ "hooks": {
+ "postToolUse": [
+ {
+ "command": "bd cursor-hook postToolUse"
+ }
+ ],
+ "preCompact": [
+ {
+ "command": "bd cursor-hook preCompact"
+ }
+ ],
+ "sessionStart": [
+ {
+ "command": "bd cursor-hook sessionStart"
+ }
+ ]
+ },
+ "version": 1
+}
diff --git a/.cursor/rules/beads.mdc b/.cursor/rules/beads.mdc
new file mode 100644
index 0000000..7bfa5bb
--- /dev/null
+++ b/.cursor/rules/beads.mdc
@@ -0,0 +1,67 @@
+---
+alwaysApply: true
+---
+
+
+
+
+# Beads Issue Tracking
+
+This project uses [Beads (bd)](https://github.com/gastownhall/beads) for issue tracking.
+
+## Core Rules
+
+- Track ALL work in bd (never use markdown TODOs or comment-based task lists)
+- Use `bd ready` to find available work
+- Use `bd create` to track new issues/tasks/bugs
+- Treat commit, push, and Dolt remote sync as policy-controlled handoff actions
+- Run `bd prime` for complete workflow context (SSOT for operational commands)
+- Default to conservative git authority: report status and proposed commands unless the user, orchestrator, or repository profile explicitly authorizes commit/sync/push
+
+## Quick Reference
+
+```bash
+bd prime # Load complete workflow context (SSOT)
+bd ready # Show issues ready to work (no blockers)
+bd list --status=open # List all open issues
+bd create "title" -t task -p 2 # Create new issue
+bd update --claim # Claim work atomically
+bd unclaim # Release stuck issue (agent crashed)
+bd close # Mark complete
+bd dep add # Add dependency
+bd dolt push # Sync with remote when authorized
+```
+
+## Workflow
+
+1. Check for ready work: `bd ready`
+2. Claim an issue atomically: `bd update --claim`
+3. Do the work
+4. Mark complete: `bd close `
+5. Handoff: report changed files, validation, issue status, and any proposed commit/sync/push commands
+
+## Issue Types
+
+- `bug` - Something broken
+- `feature` - New functionality
+- `task` - Work item (tests, docs, refactoring)
+- `epic` - Large feature with subtasks
+- `chore` - Maintenance (dependencies, tooling)
+
+## Priorities
+
+- `0` - Critical (security, data loss, broken builds)
+- `1` - High (major features, important bugs)
+- `2` - Medium (default, nice-to-have)
+- `3` - Low (polish, optimization)
+- `4` - Backlog (future ideas)
+
+## Context Loading
+
+Run `bd prime` to get complete workflow documentation in AI-optimized format.
+`bd prime` is the single source of truth for operational commands and session workflow.
+
+For detailed docs: see AGENTS.md, the beads quickstart
+(https://github.com/gastownhall/beads/blob/main/docs/getting-started/quickstart.md), or run `bd --help`
+
+
diff --git a/.gitignore b/.gitignore
index 4488b71..7275f9a 100644
--- a/.gitignore
+++ b/.gitignore
@@ -25,3 +25,7 @@ coverage.*
# Local env overrides (never commit)
.env
.env.local
+
+# Beads / Dolt files (added by bd init)
+.beads/proxieddb/
+*.gate.lock*
diff --git a/AGENTS.md b/AGENTS.md
new file mode 100644
index 0000000..cf2ac15
--- /dev/null
+++ b/AGENTS.md
@@ -0,0 +1,128 @@
+# Agent Instructions
+
+This project uses **bd** (beads) for issue tracking. Run `bd prime` for full workflow context.
+
+> **Architecture in one line:** Issues live in a local Dolt database
+> (`.beads/dolt/`); cross-machine sync uses `bd dolt push/pull` (a
+> git-compatible protocol), stored under `refs/dolt/data` on your git
+> remote — separate from `refs/heads/*` where your code lives.
+> `.beads/issues.jsonl` is a passive export, not the wire protocol.
+>
+> See [sync-concepts](https://github.com/gastownhall/beads/blob/main/docs/core-concepts/sync-concepts.md)
+> for the one-screen overview and anti-patterns (don't treat JSONL as the
+> source of truth; don't `bd import` during normal operation; don't
+> reach for third-party Dolt hosting before trying the default).
+
+## Quick Reference
+
+```bash
+bd ready # Find available work
+bd show # View issue details
+bd update --claim # Claim work atomically
+bd close # Complete work
+bd dolt push # Push beads data to remote
+```
+
+## Non-Interactive Shell Commands
+
+**ALWAYS use non-interactive flags** with file operations to avoid hanging on confirmation prompts.
+
+Shell commands like `cp`, `mv`, and `rm` may be aliased to include `-i` (interactive) mode on some systems, causing the agent to hang indefinitely waiting for y/n input.
+
+**Use these forms instead:**
+```bash
+# Force overwrite without prompting
+cp -f source dest # NOT: cp source dest
+mv -f source dest # NOT: mv source dest
+rm -f file # NOT: rm file
+
+# For recursive operations
+rm -rf directory # NOT: rm -r directory
+cp -rf source dest # NOT: cp -r source dest
+```
+
+**Other commands that may prompt:**
+- `scp` - use `-o BatchMode=yes` for non-interactive
+- `ssh` - use `-o BatchMode=yes` to fail instead of prompting
+- `apt-get` - use `-y` flag
+- `brew` - use `HOMEBREW_NO_AUTO_UPDATE=1` env var
+
+
+## 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/core-concepts/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/core-concepts/sync-concepts.md for details and anti-patterns.
+
diff --git a/CLAUDE.md b/CLAUDE.md
new file mode 100644
index 0000000..b6674ae
--- /dev/null
+++ b/CLAUDE.md
@@ -0,0 +1,77 @@
+# Project Instructions for AI Agents
+
+This file provides instructions and context for AI coding agents working on this project.
+
+
+## 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/core-concepts/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.
+
+
+
+## Build & Test
+
+_Add your build and test commands here_
+
+```bash
+# Example:
+# npm install
+# npm test
+```
+
+## Architecture Overview
+
+_Add a brief overview of your project architecture_
+
+## Conventions & Patterns
+
+_Add your project-specific conventions here_