bd init: initialize beads issue tracking
23 unmodified lines242526272828293031323323 unmodified lines
/result/.direnv
/.scratchpadNo newline at end of file/.scratchpad
# Beads / Dolt files (added by bd init).dolt/*.db.beads-credential-key123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081828384858687888990919293949596# 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.md](https://github.com/gastownhall/beads/blob/main/docs/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
```bashbd ready # Find available workbd show <id> # View issue detailsbd update <id> --claim # Claim work atomicallybd close <id> # Complete workbd 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 promptingcp -f source dest # NOT: cp source destmv -f source dest # NOT: mv source destrm -f file # NOT: rm file
# For recursive operationsrm -rf directory # NOT: rm -r directorycp -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
<!-- BEGIN BEADS INTEGRATION v:1 profile:minimal hash:7510c1e2 -->## Beads Issue Tracker
This project uses **bd (beads)** for issue tracking. Run `bd prime` to see full workflow context and commands.
### Quick Reference
```bashbd ready # Find available workbd show <id> # View issue detailsbd update <id> --claim # Claim workbd close <id> # 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.
## Session Completion
**When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds.
**MANDATORY WORKFLOW:**
1. **File issues for remaining work** - Create issues for anything that needs follow-up2. **Run quality gates** (if code changed) - Tests, linters, builds3. **Update issue status** - Close finished work, update in-progress items4. **PUSH TO REMOTE** - This is MANDATORY: ```bash git pull --rebase git push git status # MUST show "up to date with origin" ```5. **Clean up** - Clear stashes, prune remote branches6. **Verify** - All changes committed AND pushed7. **Hand off** - Provide context for next session
**CRITICAL RULES:**- Work is NOT complete until `git push` succeeds- NEVER stop before pushing - that leaves work stranded locally- NEVER say "ready to push when you are" - YOU must push- If push fails, resolve and retry until it succeeds<!-- END BEADS INTEGRATION -->12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970# Project Instructions for AI Agents
This file provides instructions and context for AI coding agents working on this project.
<!-- BEGIN BEADS INTEGRATION v:1 profile:minimal hash:7510c1e2 -->## Beads Issue Tracker
This project uses **bd (beads)** for issue tracking. Run `bd prime` to see full workflow context and commands.
### Quick Reference
```bashbd ready # Find available workbd show <id> # View issue detailsbd update <id> --claim # Claim workbd close <id> # 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.
## Session Completion
**When ending a work session**, you MUST complete ALL steps below. Work is NOT complete until `git push` succeeds.
**MANDATORY WORKFLOW:**
1. **File issues for remaining work** - Create issues for anything that needs follow-up2. **Run quality gates** (if code changed) - Tests, linters, builds3. **Update issue status** - Close finished work, update in-progress items4. **PUSH TO REMOTE** - This is MANDATORY: ```bash git pull --rebase git push git status # MUST show "up to date with origin" ```5. **Clean up** - Clear stashes, prune remote branches6. **Verify** - All changes committed AND pushed7. **Hand off** - Provide context for next session
**CRITICAL RULES:**- Work is NOT complete until `git push` succeeds- NEVER stop before pushing - that leaves work stranded locally- NEVER say "ready to push when you are" - YOU must push- If push fails, resolve and retry until it succeeds<!-- END BEADS INTEGRATION -->
## 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_12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455565758596061626364656667686970# Dolt database (managed by Dolt, not git)dolt/embeddeddolt/
# Runtime filesbd.sockbd.sock.startlocksync-state.jsonlast-touched.exclusive-lock
# Daemon runtime (lock, log, pid)daemon.*
# Push state (runtime, per-machine)push-state.json
# Lock files (various runtime locks)*.lock
# Credential key (encryption key for federation peer auth — never commit).beads-credential-key
# Local version tracking (prevents upgrade notification spam after git ops).local_version
# Worktree redirect file (contains relative path to main repo's .beads/)# Must not be committed as paths would be wrong in other clonesredirect
# Sync state (local-only, per-machine)# These files are machine-specific and should not be shared across clones.sync.lockexport-state/export-state.json
# Ephemeral store (SQLite - wisps/molecules, intentionally not versioned)ephemeral.sqlite3ephemeral.sqlite3-journalephemeral.sqlite3-walephemeral.sqlite3-shm
# Dolt server management (auto-started by bd)dolt-server.piddolt-server.logdolt-server.lockdolt-server.portdolt-server.activity
# Corrupt backup directories (created by bd doctor --fix recovery)*.corrupt.backup/
# Backup data (auto-exported JSONL, local-only)backup/
# Per-project environment file (Dolt connection config, GH#2520).env
# Legacy files (from pre-Dolt versions)*.db*.db?**.db-journal*.db-wal*.db-shmdb.sqlitebd.db# NOTE: Do NOT add negation patterns here.# 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.123456789101112131415161718192021222324252627282930313233343536373839404142434445464748495051525354555657585960616263646566676869707172737475767778798081# Beads - AI-Native Issue Tracking
Welcome to Beads! This repository uses **Beads** for issue tracking - a modern, AI-native tool designed to live directly in your codebase alongside your code.
## What is Beads?
Beads is issue tracking that lives in your repo, making it perfect for AI coding agents and developers who want their issues close to their code. No web UI required - everything works through the CLI and integrates seamlessly with git.
**Learn more:** [github.com/steveyegge/beads](https://github.com/steveyegge/beads)
## Quick Start
### Essential Commands
```bash# Create new issuesbd create "Add user authentication"
# View all issuesbd list
# View issue detailsbd show <issue-id>
# Update issue statusbd update <issue-id> --claimbd update <issue-id> --status done
# Sync with Dolt remotebd dolt push```
### Working with Issues
Issues in Beads are:- **Git-native**: Stored in Dolt database with version control and branching- **AI-friendly**: CLI-first design works perfectly with AI coding agents- **Branch-aware**: Issues can follow your branch workflow- **Always in sync**: Auto-syncs with your commits
## Why Beads?
✨ **AI-Native Design**- Built specifically for AI-assisted development workflows- CLI-first interface works seamlessly with AI coding agents- No context switching to web UIs
🚀 **Developer Focused**- Issues live in your repo, right next to your code- Works offline, syncs when you push- Fast, lightweight, and stays out of your way
🔧 **Git Integration**- Automatic sync with git commits- Branch-aware issue tracking- Dolt-native three-way merge resolution
## Get Started with Beads
Try Beads in your own projects:
```bash# Install Beadscurl -sSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
# Initialize in your repobd init
# Create your first issuebd create "Try out Beads"```
## Learn More
- **Documentation**: [github.com/steveyegge/beads/docs](https://github.com/steveyegge/beads/tree/main/docs)- **Quick Start Guide**: Run `bd quickstart`- **Examples**: [github.com/steveyegge/beads/examples](https://github.com/steveyegge/beads/tree/main/examples)
---
*Beads: Issue tracking that moves at the speed of thought* ⚡12345678910111213141516171819202122232425262728293031323334353637383940414243444546474849505152535455# Beads Configuration File# This file configures default behavior for all bd commands in this repository# All settings can also be set via environment variables (BD_* prefix)# or overridden with command-line flags
# Issue prefix for this repository (used by bd init)# If not set, bd init will auto-detect from directory name# Example: issue-prefix: "myproject" creates issues like "myproject-1", "myproject-2", etc.# issue-prefix: ""
# Use no-db mode: JSONL-only, no Dolt database# When true, bd will use .beads/issues.jsonl as the source of truth# no-db: false
# Enable JSON output by default# json: false
# Feedback title formatting for mutating commands (create/update/close/dep/edit)# 0 = hide titles, N > 0 = truncate to N characters# output:# title-length: 255
# Default actor for audit trails (overridden by BEADS_ACTOR or --actor)# actor: ""
# Export events (audit trail) to .beads/events.jsonl on each flush/sync# When enabled, new events are appended incrementally using a high-water mark.# Use 'bd export --events' to trigger manually regardless of this setting.# events-export: false
# Multi-repo configuration (experimental - bd-307)# Allows hydrating from multiple repositories and routing writes to the correct database# repos:# primary: "." # Primary repo (where this database lives)# additional: # Additional repos to hydrate from (read-only)# - ~/beads-planning # Personal planning repo# - ~/work-planning # Work planning repo
# JSONL backup (periodic export for off-machine recovery)# Auto-enabled when a git remote exists. Override explicitly:# backup:# enabled: false # Disable auto-backup entirely# interval: 15m # Minimum time between auto-exports# git-push: false # Disable git push (export locally only)# git-repo: "" # Separate git repo for backups (default: project repo)
# Integration settings (access with 'bd config get/set')# Non-secret keys (stored in the database):# - jira.url, jira.project# - linear.team_id# - github.org, github.repo## 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 .beads /interactions.jsonl no changes to the file itself
1234567{ "database": "dolt", "backend": "dolt", "dolt_mode": "embedded", "dolt_database": "nucleus", "project_id": "bf0b94c2-7ce1-4a31-87a1-b40a40ae1e2f"}No newline at end of file1234567891011121314151617181920212223242526{ "hooks": { "PreCompact": [ { "hooks": [ { "command": "bd prime", "type": "command" } ], "matcher": "" } ], "SessionStart": [ { "hooks": [ { "command": "bd prime", "type": "command" } ], "matcher": "" } ] }}No newline at end of file123456789101112131415161718192021222324#!/usr/bin/env sh# --- BEGIN BEADS INTEGRATION v1.0.4 ---# 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} if command -v timeout >/dev/null 2>&1; then timeout "$_bd_timeout" bd hooks run post-checkout "$@" _bd_exit=$? if [ $_bd_exit -eq 124 ]; then echo >&2 "beads: hook 'post-checkout' timed out after ${_bd_timeout}s — continuing without beads" _bd_exit=0 fi else bd hooks run post-checkout "$@" _bd_exit=$? 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; fifi# --- END BEADS INTEGRATION v1.0.4 ---123456789101112131415161718192021222324#!/usr/bin/env sh# --- BEGIN BEADS INTEGRATION v1.0.4 ---# 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} if command -v timeout >/dev/null 2>&1; then timeout "$_bd_timeout" bd hooks run post-merge "$@" _bd_exit=$? if [ $_bd_exit -eq 124 ]; then echo >&2 "beads: hook 'post-merge' timed out after ${_bd_timeout}s — continuing without beads" _bd_exit=0 fi else bd hooks run post-merge "$@" _bd_exit=$? 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; fifi# --- END BEADS INTEGRATION v1.0.4 ---123456789101112131415161718192021222324#!/usr/bin/env sh# --- BEGIN BEADS INTEGRATION v1.0.4 ---# 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} if command -v timeout >/dev/null 2>&1; then timeout "$_bd_timeout" bd hooks run pre-commit "$@" _bd_exit=$? if [ $_bd_exit -eq 124 ]; then echo >&2 "beads: hook 'pre-commit' timed out after ${_bd_timeout}s — continuing without beads" _bd_exit=0 fi else bd hooks run pre-commit "$@" _bd_exit=$? 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; fifi# --- END BEADS INTEGRATION v1.0.4 ---123456789101112131415161718192021222324#!/usr/bin/env sh# --- BEGIN BEADS INTEGRATION v1.0.4 ---# 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} if command -v timeout >/dev/null 2>&1; then timeout "$_bd_timeout" bd hooks run pre-push "$@" _bd_exit=$? if [ $_bd_exit -eq 124 ]; then echo >&2 "beads: hook 'pre-push' timed out after ${_bd_timeout}s — continuing without beads" _bd_exit=0 fi else bd hooks run pre-push "$@" _bd_exit=$? 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; fifi# --- END BEADS INTEGRATION v1.0.4 ---123456789101112131415161718192021222324#!/usr/bin/env sh# --- BEGIN BEADS INTEGRATION v1.0.4 ---# 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} if command -v timeout >/dev/null 2>&1; then timeout "$_bd_timeout" bd hooks run prepare-commit-msg "$@" _bd_exit=$? if [ $_bd_exit -eq 124 ]; then echo >&2 "beads: hook 'prepare-commit-msg' timed out after ${_bd_timeout}s — continuing without beads" _bd_exit=0 fi else bd hooks run prepare-commit-msg "$@" _bd_exit=$? 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; fifi# --- END BEADS INTEGRATION v1.0.4 ---