viktor/beadboard
1
0
Fork 0
Code Issues Pull requests Projects Releases Packages Wiki Activity Actions

checkpoint: pre-split branch cleanup

Browse source
This commit is contained in:
ZenchantLive 2026-03-03 16:43:42 -08:00
parent 4c2ae2e5b7
commit b5db7a7753
276 changed files with 35912 additions and 60119 deletions
Download patch file Download diff file Expand all files Collapse all files

106
help/workflows/agent_bead_workflow.txt
View file

@ -1,53 +1,53 @@
# Agent Workflow for Beadboard
As an agent working in this repository, you must follow these rules when managing tasks using `bd`.
---
## 1. Finding Work
Before starting any new work, check if there's already an open task for it.
```bash
bd ready
```
*If a task is ready, pick it up instead of creating a duplicate.*
## 2. Starting Work / Tracking Plans
When asked to perform non-trivial work without an existing task, **always create a task**.
Do **not** keep your plan in free-form text. Create a task with `priority 0`.
```bash
bd create "Short descriptive title of the work" -p 0
```
Update the status to `in_progress` if you are working on it:
```bash
bd set-state <task-id> in_progress
```
## 3. Working within Tasks (task.md)
Update the local `<appDataDir>/brain/<conversation-id>/task.md` using the checklist `[ ]`, `[/]`, `[x]` to maintain your internal progress while working. Also update the `bd` task if you have significant architectural notes.
## 4. Dependencies
If your task depends on another task being completed first, declare the block:
```bash
# Link: your task is blocked by another task
# First run bd dep add, it will prompt you interactively.
# Or use the appropriate arguments if you know them.
# The user prefers bd handle these rather than prose "do X after Y"
```
## 5. Finishing Work
When you have finished a task, completed your tests, and verified it works (run your lint/typecheck steps), you must close the task.
1. **Verify completion**: `bun run typecheck && bun run lint`
2. **Close the bead**:
```bash
# You can use bd update or bd close
bd status <task-id> # To view it
bd close <task-id> # To mark it closed
```
3. **Summarize**: Leave a summary of what changed. (You can do this by using bd edit or through a comment if bd supports it, otherwise summarize in your git commit).
## 6. Verifying Past Work (Recently Closed Beads)
If you need to know what was just finished (e.g. to see if a bead was successfully closed), view the recently closed beads:
```bash
bd query "status=closed" --sort closed --reverse --limit 5
```
# Agent Workflow for Beadboard
As an agent working in this repository, you must follow these rules when managing tasks using `bd`.
---
## 1. Finding Work
Before starting any new work, check if there's already an open task for it.
```bash
bd ready
```
*If a task is ready, pick it up instead of creating a duplicate.*
## 2. Starting Work / Tracking Plans
When asked to perform non-trivial work without an existing task, **always create a task**.
Do **not** keep your plan in free-form text. Create a task with `priority 0`.
```bash
bd create "Short descriptive title of the work" -p 0
```
Update the status to `in_progress` if you are working on it:
```bash
bd set-state <task-id> in_progress
```
## 3. Working within Tasks (task.md)
Update the local `<appDataDir>/brain/<conversation-id>/task.md` using the checklist `[ ]`, `[/]`, `[x]` to maintain your internal progress while working. Also update the `bd` task if you have significant architectural notes.
## 4. Dependencies
If your task depends on another task being completed first, declare the block:
```bash
# Link: your task is blocked by another task
# First run bd dep add, it will prompt you interactively.
# Or use the appropriate arguments if you know them.
# The user prefers bd handle these rather than prose "do X after Y"
```
## 5. Finishing Work
When you have finished a task, completed your tests, and verified it works (run your lint/typecheck steps), you must close the task.
1. **Verify completion**: `bun run typecheck && bun run lint`
2. **Close the bead**:
```bash
# You can use bd update or bd close
bd status <task-id> # To view it
bd close <task-id> # To mark it closed
```
3. **Summarize**: Leave a summary of what changed. (You can do this by using bd edit or through a comment if bd supports it, otherwise summarize in your git commit).
## 6. Verifying Past Work (Recently Closed Beads)
If you need to know what was just finished (e.g. to see if a bead was successfully closed), view the recently closed beads:
```bash
bd query "status=closed" --sort closed --reverse --limit 5
```

104
help/workflows/dolt_backend_workflow.txt
View file

@ -1,52 +1,52 @@
# Beadboard Dolt System Workflow
Beadboard supports an optional **Dolt storage backend**. Dolt is a SQL database with git-like version control, enabling advanced features like branching, merging, and historic diffs for your issue data.
If your environment has Dolt enabled (no CGO build errors when using `bd`), you have access to powerful new version control commands. They behave similarly to `git` but operate purely on Beadboard issues.
## 1. Branching
You can create branches of your issue database, to test speculative features or isolate a swarm of issues before merging them into main.
- **List all branches**:
```bash
bd branch
```
- **Create a new branch**:
```bash
bd branch <branch-name>
```
## 2. Version Control (Commit & Merge)
Use `bd vc` to manage commits on your branch.
- **View status of current branch**:
```bash
bd vc status
```
- **Create a commit**:
```bash
bd vc commit
```
- **Merge a branch**:
```bash
bd vc merge <branch-to-merge>
```
*Note: You can also rely on `--dolt-auto-commit=on` (which can be set in config) to automatically commit changes after write operations like `bd create` or `bd update`.*
## 3. Viewing Diffs
You can view the exact issue changes (created, deleted, modified) between two commits or branches.
- **Compare current state against a branch**:
```bash
bd diff main feature-branch
```
- **Compare history**:
```bash
bd diff HEAD~5 HEAD # Show changes in the last 5 commits
```
## Summary for Agents
If you receive an error about `dolt backend requires CGO` when running `bd ready`, it means the Dolt features are not available on this specific build. You must fall back to standard `bd` commands which use SQLite by default and sync via JSONL files.
However, when working in a Dolt-enabled environment, you should proactively create a branch when starting a large Epic (`bd branch feature-xyz`), commit your `bd` issue changes natively tracking the state (`bd vc commit`), and merge them back when the epic is verified (`bd vc merge`).
# Beadboard Dolt System Workflow
Beadboard supports an optional **Dolt storage backend**. Dolt is a SQL database with git-like version control, enabling advanced features like branching, merging, and historic diffs for your issue data.
If your environment has Dolt enabled (no CGO build errors when using `bd`), you have access to powerful new version control commands. They behave similarly to `git` but operate purely on Beadboard issues.
## 1. Branching
You can create branches of your issue database, to test speculative features or isolate a swarm of issues before merging them into main.
- **List all branches**:
```bash
bd branch
```
- **Create a new branch**:
```bash
bd branch <branch-name>
```
## 2. Version Control (Commit & Merge)
Use `bd vc` to manage commits on your branch.
- **View status of current branch**:
```bash
bd vc status
```
- **Create a commit**:
```bash
bd vc commit
```
- **Merge a branch**:
```bash
bd vc merge <branch-to-merge>
```
*Note: You can also rely on `--dolt-auto-commit=on` (which can be set in config) to automatically commit changes after write operations like `bd create` or `bd update`.*
## 3. Viewing Diffs
You can view the exact issue changes (created, deleted, modified) between two commits or branches.
- **Compare current state against a branch**:
```bash
bd diff main feature-branch
```
- **Compare history**:
```bash
bd diff HEAD~5 HEAD # Show changes in the last 5 commits
```
## Summary for Agents
If you receive an error about `dolt backend requires CGO` when running `bd ready`, it means the Dolt features are not available on this specific build. You must fall back to standard `bd` commands which use SQLite by default and sync via JSONL files.
However, when working in a Dolt-enabled environment, you should proactively create a branch when starting a large Epic (`bd branch feature-xyz`), commit your `bd` issue changes natively tracking the state (`bd vc commit`), and merge them back when the epic is verified (`bd vc merge`).

98
help/workflows/viewing_recent_closed_beads.txt
View file

@ -1,49 +1,49 @@
# Viewing Recently Closed Beads
When you need to find beads (tasks, issues) that were recently closed, use `bd query` or `bd list` with date filters.
The user rule indicates a need to "correctly view the last closed beads (there is some sort of filter for recency)".
## Method 1: Using `bd query`
`bd query` supports a simple query language with relative and absolute dates.
1. **View closed beads in the last X days**
```bash
bd query "status=closed AND updated>2d" --sort updated
```
*This finds beads closed and updated within the last 2 days, sorted chronologically with newest at the bottom.*
2. **View closed beads in the last 24 hours**
```bash
bd query "status=closed AND updated>24h" --sort updated
```
3. **View everything closed**
```bash
bd query "status=closed" --sort closed --limit 10 --reverse
```
*This shows the 10 most recently closed beads (requires --reverse so limit grabs the newest).*
## Method 2: Using `bd list`
`bd list` has specific flags for filtering by closure date.
1. **View closed beads using --closed-after**
```bash
bd list --status closed --closed-after "7d" --sort closed --reverse
```
Wait, the `--closed-after` flag expects YYYY-MM-DD or RFC3339. The better approach for relative dates is `bd query`.
However, if using absolute dates:
```bash
bd list --status closed --closed-after 2025-01-01 --sort closed --reverse
```
## Summary for Agents:
**Always use `bd query` with relative time for the best results** when checking recency.
To view recently closed beads (within the last 3 days) in standard terminal chronological order (oldest at top, newest at bottom):
**`bd query "status=closed AND closed>3d" --sort closed`**
To get just the last 5 closed beads (note: you must use --reverse to get the most recent ones when using --limit):
**`bd query "status=closed" --sort closed --reverse --limit 5`**
# Viewing Recently Closed Beads
When you need to find beads (tasks, issues) that were recently closed, use `bd query` or `bd list` with date filters.
The user rule indicates a need to "correctly view the last closed beads (there is some sort of filter for recency)".
## Method 1: Using `bd query`
`bd query` supports a simple query language with relative and absolute dates.
1. **View closed beads in the last X days**
```bash
bd query "status=closed AND updated>2d" --sort updated
```
*This finds beads closed and updated within the last 2 days, sorted chronologically with newest at the bottom.*
2. **View closed beads in the last 24 hours**
```bash
bd query "status=closed AND updated>24h" --sort updated
```
3. **View everything closed**
```bash
bd query "status=closed" --sort closed --limit 10 --reverse
```
*This shows the 10 most recently closed beads (requires --reverse so limit grabs the newest).*
## Method 2: Using `bd list`
`bd list` has specific flags for filtering by closure date.
1. **View closed beads using --closed-after**
```bash
bd list --status closed --closed-after "7d" --sort closed --reverse
```
Wait, the `--closed-after` flag expects YYYY-MM-DD or RFC3339. The better approach for relative dates is `bd query`.
However, if using absolute dates:
```bash
bd list --status closed --closed-after 2025-01-01 --sort closed --reverse
```
## Summary for Agents:
**Always use `bd query` with relative time for the best results** when checking recency.
To view recently closed beads (within the last 3 days) in standard terminal chronological order (oldest at top, newest at bottom):
**`bd query "status=closed AND closed>3d" --sort closed`**
To get just the last 5 closed beads (note: you must use --reverse to get the most recent ones when using --limit):
**`bd query "status=closed" --sort closed --reverse --limit 5`**