(pre-development) Stars! PBeM service on Kubernetes
Add open questions and deferred decision framework for turn-taking policies
+226
+52
.beads/.gitignore
+52
.beads/.gitignore
···
1
+
# Dolt database (managed by Dolt, not git)
2
+
dolt/
3
+
dolt-access.lock
4
+
dolt-monitor.pid.lock
5
+
6
+
# Runtime files
7
+
bd.sock
8
+
bd.sock.startlock
9
+
sync-state.json
10
+
last-touched
11
+
12
+
# Local version tracking (prevents upgrade notification spam after git ops)
13
+
.local_version
14
+
15
+
# Worktree redirect file (contains relative path to main repo's .beads/)
16
+
# Must not be committed as paths would be wrong in other clones
17
+
redirect
18
+
19
+
# Sync state (local-only, per-machine)
20
+
# These files are machine-specific and should not be shared across clones
21
+
.sync.lock
22
+
export-state/
23
+
24
+
# Ephemeral store (SQLite - wisps/molecules, intentionally not versioned)
25
+
ephemeral.sqlite3
26
+
ephemeral.sqlite3-journal
27
+
ephemeral.sqlite3-wal
28
+
ephemeral.sqlite3-shm
29
+
30
+
# Dolt server management (auto-started by bd)
31
+
dolt-server.pid
32
+
dolt-server.log
33
+
dolt-server.lock
34
+
dolt-server.port
35
+
dolt-server.activity
36
+
dolt-monitor.pid
37
+
38
+
# Backup data (auto-exported JSONL, local-only)
39
+
backup/
40
+
41
+
# Legacy files (from pre-Dolt versions)
42
+
*.db
43
+
*.db?*
44
+
*.db-journal
45
+
*.db-wal
46
+
*.db-shm
47
+
db.sqlite
48
+
bd.db
49
+
# NOTE: Do NOT add negation patterns here.
50
+
# They would override fork protection in .git/info/exclude.
51
+
# Config files (metadata.json, config.yaml) are tracked by git by default
52
+
# since no pattern above ignores them.
+81
.beads/README.md
+81
.beads/README.md
···
1
+
# Beads - AI-Native Issue Tracking
2
+
3
+
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.
4
+
5
+
## What is Beads?
6
+
7
+
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.
8
+
9
+
**Learn more:** [github.com/steveyegge/beads](https://github.com/steveyegge/beads)
10
+
11
+
## Quick Start
12
+
13
+
### Essential Commands
14
+
15
+
```bash
16
+
# Create new issues
17
+
bd create "Add user authentication"
18
+
19
+
# View all issues
20
+
bd list
21
+
22
+
# View issue details
23
+
bd show <issue-id>
24
+
25
+
# Update issue status
26
+
bd update <issue-id> --claim
27
+
bd update <issue-id> --status done
28
+
29
+
# Sync with Dolt remote
30
+
bd dolt push
31
+
```
32
+
33
+
### Working with Issues
34
+
35
+
Issues in Beads are:
36
+
- **Git-native**: Stored in Dolt database with version control and branching
37
+
- **AI-friendly**: CLI-first design works perfectly with AI coding agents
38
+
- **Branch-aware**: Issues can follow your branch workflow
39
+
- **Always in sync**: Auto-syncs with your commits
40
+
41
+
## Why Beads?
42
+
43
+
✨ **AI-Native Design**
44
+
- Built specifically for AI-assisted development workflows
45
+
- CLI-first interface works seamlessly with AI coding agents
46
+
- No context switching to web UIs
47
+
48
+
🚀 **Developer Focused**
49
+
- Issues live in your repo, right next to your code
50
+
- Works offline, syncs when you push
51
+
- Fast, lightweight, and stays out of your way
52
+
53
+
🔧 **Git Integration**
54
+
- Automatic sync with git commits
55
+
- Branch-aware issue tracking
56
+
- Dolt-native three-way merge resolution
57
+
58
+
## Get Started with Beads
59
+
60
+
Try Beads in your own projects:
61
+
62
+
```bash
63
+
# Install Beads
64
+
curl -sSL https://raw.githubusercontent.com/steveyegge/beads/main/scripts/install.sh | bash
65
+
66
+
# Initialize in your repo
67
+
bd init
68
+
69
+
# Create your first issue
70
+
bd create "Try out Beads"
71
+
```
72
+
73
+
## Learn More
74
+
75
+
- **Documentation**: [github.com/steveyegge/beads/docs](https://github.com/steveyegge/beads/tree/main/docs)
76
+
- **Quick Start Guide**: Run `bd quickstart`
77
+
- **Examples**: [github.com/steveyegge/beads/examples](https://github.com/steveyegge/beads/tree/main/examples)
78
+
79
+
---
80
+
81
+
*Beads: Issue tracking that moves at the speed of thought* ⚡
+54
.beads/config.yaml
+54
.beads/config.yaml
···
1
+
# Beads Configuration File
2
+
# This file configures default behavior for all bd commands in this repository
3
+
# All settings can also be set via environment variables (BD_* prefix)
4
+
# or overridden with command-line flags
5
+
6
+
# Issue prefix for this repository (used by bd init)
7
+
# If not set, bd init will auto-detect from directory name
8
+
# Example: issue-prefix: "myproject" creates issues like "myproject-1", "myproject-2", etc.
9
+
# issue-prefix: ""
10
+
11
+
# Use no-db mode: JSONL-only, no Dolt database
12
+
# When true, bd will use .beads/issues.jsonl as the source of truth
13
+
# no-db: false
14
+
15
+
# Enable JSON output by default
16
+
# json: false
17
+
18
+
# Feedback title formatting for mutating commands (create/update/close/dep/edit)
19
+
# 0 = hide titles, N > 0 = truncate to N characters
20
+
# output:
21
+
# title-length: 255
22
+
23
+
# Default actor for audit trails (overridden by BD_ACTOR or --actor)
24
+
# actor: ""
25
+
26
+
# Export events (audit trail) to .beads/events.jsonl on each flush/sync
27
+
# When enabled, new events are appended incrementally using a high-water mark.
28
+
# Use 'bd export --events' to trigger manually regardless of this setting.
29
+
# events-export: false
30
+
31
+
# Multi-repo configuration (experimental - bd-307)
32
+
# Allows hydrating from multiple repositories and routing writes to the correct database
33
+
# repos:
34
+
# primary: "." # Primary repo (where this database lives)
35
+
# additional: # Additional repos to hydrate from (read-only)
36
+
# - ~/beads-planning # Personal planning repo
37
+
# - ~/work-planning # Work planning repo
38
+
39
+
# JSONL backup (periodic export for off-machine recovery)
40
+
# Auto-enabled when a git remote exists. Override explicitly:
41
+
# backup:
42
+
# enabled: false # Disable auto-backup entirely
43
+
# interval: 15m # Minimum time between auto-exports
44
+
# git-push: false # Disable git push (export locally only)
45
+
# git-repo: "" # Separate git repo for backups (default: project repo)
46
+
47
+
# Integration settings (access with 'bd config get/set')
48
+
# These are stored in the database, not in this file:
49
+
# - jira.url
50
+
# - jira.project
51
+
# - linear.url
52
+
# - linear.api-key
53
+
# - github.org
54
+
# - github.repo
.beads/dolt-monitor.pid.lock
.beads/dolt-monitor.pid.lock
This is a binary file and will not be displayed.
.beads/interactions.jsonl
.beads/interactions.jsonl
This is a binary file and will not be displayed.
+7
.beads/metadata.json
+7
.beads/metadata.json
+28
doc/total-host.codex.md
+28
doc/total-host.codex.md
···
343
343
- verification and release-readiness expectations tied to `RLB-*`, `AC-*`, and `RSK-*`
344
344
- traceability and observability handoff requirements that prevent coverage drift during execution
345
345
346
+
## Open Questions and Decision Deferrals
347
+
348
+
This section records important unresolved policy space so ideas are preserved without prematurely locking implementation commitments.
349
+
350
+
### Turn-Taking Strategy Option Space (Captured Ideas)
351
+
352
+
- `TPS-IDEA-01` **Fixed cadence / blitz**: turns advance on a strict fixed interval.
353
+
- `TPS-IDEA-02` **Player-requested time extensions via ATProto**: players request more time through a lexicon action; budget models under consideration include fixed delays per game or rolling-rate delays (for example, 2 delays per 6 hours).
354
+
- `TPS-IDEA-03` **Advance when all players submit**: generation starts immediately when all required submissions are present.
355
+
- `TPS-IDEA-04` **All-submitted plus max-wait cap**: early advance when all submit, otherwise advance at a configured maximum wait timeout.
356
+
- `TPS-IDEA-05` **Time blackouts**: configured windows where no turn-clock time elapses (for example, mutually agreed nighttime windows).
357
+
358
+
### Turn Policy Dimensions Needing Design
359
+
360
+
- `OQ-TP-01` Trigger model: fixed cadence, all-submitted, hybrid, or policy composition.
361
+
- `OQ-TP-02` Timeout model: min wait, max wait, and lock boundary semantics under retries/races.
362
+
- `OQ-TP-03` Delay budget model: fixed-per-game vs rolling-window allowances, refill behavior, and carry-over policy.
363
+
- `OQ-TP-04` Blackout semantics: timezone model, daylight-saving handling, and interactions with cadence and max-wait.
364
+
- `OQ-TP-05` Eligibility and anti-abuse: who can request delays, auditability, and operator override rules.
365
+
- `OQ-TP-06` Interaction with lifecycle controls: `paused` state, manual delay/unpause, and deterministic lock behavior.
366
+
- `OQ-TP-07` Observability and traceability: required events/spans for policy decisions and player-visible outcomes.
367
+
368
+
### Deferral Rules
369
+
370
+
- `DEF-01` The `TPS-IDEA-*` entries are exploratory and are not yet `MVP` commitments.
371
+
- `DEF-02` These ideas should be promoted into `CAP-*` requirements only after policy dimensions above have explicit decisions.
372
+
- `DEF-03` Backlog tickets, if created now, should be marked as discovery/research items rather than implementation commitments.
373
+
346
374
## Deferred to Later Stages
347
375
348
376
- traceability implementation design (annotation format, report shape, CI policy)