ktim.tngl.sh
+1
.beads/issues.jsonl
+1
.beads/issues.jsonl
···
1
+
{"id":".dotfiles-1","title":"Add cleanupPeriodDays to Claude settings","description":"Add cleanupPeriodDays field set to 99999 in claude/settings.json.","status":"closed","priority":2,"issue_type":"task","created_at":"2025-10-22T04:47:25.470995-07:00","updated_at":"2025-10-22T04:48:08.574169-07:00","closed_at":"2025-10-22T04:48:08.574169-07:00","comments":[{"id":1,"issue_id":".dotfiles-1","author":"tk","text":"Added cleanupPeriodDays: 99999 to claude/settings.json.","created_at":"2025-10-22T11:47:58Z"}]}
+2
-1
.gitignore
+2
-1
.gitignore
+2
claude/CLAUDE.md
+2
claude/CLAUDE.md
···
1
+
**Note**: This project uses [bd (beads)](https://github.com/steveyegge/beads) for issue tracking. Use `bd` commands instead of markdown TODOs. See `codex/AGENTS.md` for workflow details.
2
+
1
3
# Claude Configuration
2
4
3
5
This file contains recommended configuration settings for Claude when interacting with any repository.
+94
-24
codex/AGENTS.md
+94
-24
codex/AGENTS.md
···
2
2
3
3
## beads Agent Directive
4
4
5
-
**Mission**
6
-
Use the `bd` CLI to own the single canonical workstream. Keep every task, blocker, and follow-up inside Beads so humans never have to reconcile Markdown lists again. v0.9.x expects a single active stream—finish or close the current one before spawning a new track. Default to the `bd` binary with `--json`; only reach for the MCP server when you are certain it targets this repo.
5
+
All task coordination flows through `bd`; consult the quick-start below before kicking off new work.
7
6
8
-
### Daily Loop
9
-
- Start: `bd list --status in_progress --json` to resume anything mid-flight. If nothing is active, run `bd ready --json` and pick the highest-priority issue.
10
-
- Inspect context with `bd show <id> --json`. Relay the key details back to the user before acting.
11
-
- Claim work by moving it to in-progress: `bd update <id> --status in_progress --json`. Always reflect blockers or progress changes immediately.
7
+
## Issue Tracking with bd (beads)
8
+
9
+
**IMPORTANT**: This project uses **bd (beads)** for ALL issue tracking. Do NOT use markdown TODOs, task lists, or other tracking methods.
10
+
11
+
### Why bd?
12
12
13
-
### Working Issues
14
-
- While implementing, log meaningful breadcrumbs: `bd comments add <id> "what changed / what's next"` so the next session can continue smoothly.
15
-
- If you discover a blocker, mark the current issue blocked (`bd update <id> --status blocked --json`), create the blocker issue (see below), and link them before doing anything else.
16
-
- Wrap up with `bd close <id> --reason "Short, user-facing result" --json`. If work is incomplete, reset to open and leave a comment explaining why.
13
+
- Dependency-aware: Track blockers and relationships between issues
14
+
- Git-friendly: Auto-syncs to JSONL for version control
15
+
- Agent-optimized: JSON output, ready work detection, discovered-from links
16
+
- Prevents duplicate tracking systems and confusion
17
+
18
+
### Quick Start
19
+
20
+
**Check for ready work:**
21
+
```bash
22
+
bd ready --json
23
+
```
24
+
25
+
**Create new issues:**
26
+
```bash
27
+
bd create "Issue title" -t bug|feature|task -p 0-4 --json
28
+
bd create "Issue title" -p 1 --deps discovered-from:bd-123 --json
29
+
```
17
30
18
-
### Creating & Linking Work
19
-
- New work you discover: `bd create "Title" -t bug|task|feature -p 0-4 --deps discovered-from:<current-id> --json`. Include enough description for an offline human review.
20
-
- To express hard dependencies after the fact: `bd dep add <child> <parent> --type blocks`. Use `discovered-from` for lateral context and `parent-child` for epic/subtask relationships.
21
-
- Keep priorities honest: 0 = critical, 1 = high, 2 = normal, 3 = low polish, 4 = backlog. Default to 2 if unsure.
22
-
- Use labels sparingly but consistently: `bd label add <id> backend`, `bd label remove <id> legacy`.
31
+
**Claim and update:**
32
+
```bash
33
+
bd update bd-42 --status in_progress --json
34
+
bd update bd-42 --priority 1 --json
35
+
```
23
36
24
-
### Sync & Hygiene
25
-
- Auto import/export keeps `.beads/issues.jsonl` in sync; no manual `bd export` needed unless you want an ad-hoc snapshot, and never hand-edit the JSONL or SQLite files directly.
26
-
- If you touched the repo outside `bd` (e.g., git pull with issue changes), run `bd sync --dry-run` to preview and resolve collisions before pushing.
27
-
- When the daemon auto-starts, let it run. Only fall back to `--no-daemon` if you see repeated connection failures.
37
+
**Complete work:**
38
+
```bash
39
+
bd close bd-42 --reason "Completed" --json
40
+
```
28
41
29
-
### When Unsure
30
-
- `bd quickstart` gives the official tutorial; skim it whenever the workflow feels fuzzy.
31
-
- `bd ready --limit 5 --json` surfaces the short list of unblocked issues; use it whenever you lose the plot.
32
-
- Ask the user before renumbering, renaming prefixes, or running destructive imports. These commands mutate IDs and should never be surprise operations.
42
+
### Issue Types
33
43
34
-
Stay disciplined: every piece of work goes into Beads, every state change is explicit, and every session ends with no stray in-progress issues unless intentionally paused with a comment.
44
+
- `bug` - Something broken
45
+
- `feature` - New functionality
46
+
- `task` - Work item (tests, docs, refactoring)
47
+
- `epic` - Large feature with subtasks
48
+
- `chore` - Maintenance (dependencies, tooling)
49
+
50
+
### Priorities
51
+
52
+
- `0` - Critical (security, data loss, broken builds)
53
+
- `1` - High (major features, important bugs)
54
+
- `2` - Medium (default, nice-to-have)
55
+
- `3` - Low (polish, optimization)
56
+
- `4` - Backlog (future ideas)
57
+
58
+
### Workflow for AI Agents
59
+
60
+
1. **Check ready work**: `bd ready` shows unblocked issues
61
+
2. **Claim your task**: `bd update <id> --status in_progress`
62
+
3. **Work on it**: Implement, test, document
63
+
4. **Discover new work?** Create linked issue:
64
+
- `bd create "Found bug" -p 1 --deps discovered-from:<parent-id>`
65
+
5. **Complete**: `bd close <id> --reason "Done"`
66
+
67
+
### Auto-Sync
68
+
69
+
bd automatically syncs with git:
70
+
- Exports to `.beads/issues.jsonl` after changes (5s debounce)
71
+
- Imports from JSONL when newer (e.g., after `git pull`)
72
+
- No manual export/import needed!
73
+
74
+
### MCP Server (Recommended)
75
+
76
+
If using Claude or MCP-compatible clients, install the beads MCP server:
77
+
78
+
```bash
79
+
pip install beads-mcp
80
+
```
81
+
82
+
Add to MCP config (e.g., `~/.config/claude/config.json`):
83
+
```json
84
+
{
85
+
"beads": {
86
+
"command": "beads-mcp",
87
+
"args": []
88
+
}
89
+
}
90
+
```
91
+
92
+
Then use `mcp__beads__*` functions instead of CLI commands.
93
+
94
+
### Important Rules
95
+
96
+
- ✅ Use bd for ALL task tracking
97
+
- ✅ Always use `--json` flag for programmatic use
98
+
- ✅ Link discovered work with `discovered-from` dependencies
99
+
- ✅ Check `bd ready` before asking "what should I work on?"
100
+
- ❌ Do NOT create markdown TODO lists
101
+
- ❌ Do NOT use external issue trackers
102
+
- ❌ Do NOT duplicate tracking systems
103
+
104
+
For more details, see README.md and QUICKSTART.md.
35
105
36
106
## Complexity Mitigator
37
107