beads-tasks

Files (1)

• SKILL.md

SKILL.md (first lines)

## Overview

Global task manager powered by [Beads](https://github.com/steveyegge/beads). Stores all tasks in
`~/.heyclara/beads/` as a single cross-project DB. Projects are organized via `project:<name>` labels.

## Quick Start

1. Check `which bd` — install if missing.
2. Ensure `~/.heyclara/beads/.beads` exists — `bd init` if not.
3. Set `BEATS_DIR` to your Beads workspace (for example `~/.heyclara/beads`).
4. All commands: `cd "$BEATS_DIR" && bd <command>`.
5. Always label with `--label project:<name>`.
6. Run `cd "$BEATS_DIR" && bd --help` or `bd help --all` for available commands.

## Core Commands

### Creating tasks

```bash
# Basic
bd create --title "Fix auth token refresh" --priority P2 --type bug

# With parent (subtask)
bd create --title "Extract shared logic" --priority P2 --type task --parent <parent-id>

# With description — ALWAYS add context: what's broken, links, references
bd create --title "Chat fails on long docs" --type bug --description "Fails on docs >500 pages. Ref: https://..."

# Epic (container for related tasks)
bd create --title "API performance improvements" --type epic --priority P2
```

### Updating tasks

`bd update` is the workhorse — use it for reparenting, reprioritizing, retyping, renaming:

```bash
bd update <id> --parent <new-parent-id>    # Reparent / move under epic
bd update <id> --parent ""                 # Remove parent (make top-level)
bd update <id> --priority P1               # Change priority
bd update <id> --type bug                  # Change type
bd update <id> --title "Better title"      # Rename
bd update <id> --status in_progress        # Start work
bd update <id> --description "..."         # Add/replace description
bd update <id> --add-label personal        # Add label
bd update <id> --set-labels bug,urgent     # Replace all labels
bd update <id> --claim                     # Atomically claim work
bd update <id> --set-metadata team=platform # Set task-scoped metadata
```

Chain multiple updates: `bd update <id> --priority P1 --type bug --parent <parent-id>`

### Viewing tasks

```bash
bd list                          # Open tasks (tree view)
bd list --all                    # Include closed/deferred tasks
bd list --label project:<name>   # Filter by project
bd ready                         # Ready work with blocker-aware semantics
bd ready --claim                 # Atomically claim the first matching ready issue
bd show <id>                     # Full details of a task
bd show <id> --long              # Full details, including extended metadata
bd show --current --long         # Current/last touched issue with metadata
bd children <id>                 # List children of a parent
```

### Closing tasks

```bash
bd close <id>                    # Close a task
bd reopen <id>                   # Reopen if closed prematurely
```

**Warning:** Closing a parent does NOT close or reparent its children. If a parent epic is done but children remain open, reparent them first or they become orphaned top-level items.

## Decision Points

- User says "add a task" / "remind me to" / "track this" → `bd create`
- User says "what's on my plate" / "show tasks" → `bd list`
- User asks about a specific task → `bd show <id>`
- User says "done with X" / "finished" → `bd close <id>`
- User wants to see cross-project work → `bd list` (no project filter)
- User wants project-specific view → `bd list --label project:<name>`
- bd not installed → offer install, don't silently fail
- Ephemeral/conversation-only tracking → use conversation context, not beads
- `bd set-state ... state=...` is for operational metadata only; it does not change the task status shown in list.

## Agent Session Tracking

When a Beads task is worked in Claude Code, Codex, or another agent CLI, store the active session on the task as metadata. Do not invent session IDs yourself; let the tool create the session, then attach the discovered session ID to the bead.

Use one shared metadata schema for all tools:

```bash
session_tool=codex|claude
session_id=<tool-created-session-id>
session_cwd=<absolute repo/worktree path>
session_resume_cmd=<exact resume command>
session_attached_at=<ISO timestamp>
```

Attach a session after starting or identifying it:

```bash
cd "$BEATS_DIR"
bd update <id> --claim
bd update <id> \
  --set-metadata session_tool=codex \
  --set-metadata session_id="$sid" \
  --set-metadata session_cwd="$PWD" \
  --set-metadata session_resume_cmd="cd $PWD && codex resume $sid" \
  --set-metadata session_attached_at="$(date -u +%Y-%m-%dT%H:%M:%SZ)"
bd note <id> "Attached codex session $sid"
```

For Claude, use the same keys and a Claude resume command:

```bash
bd update <id> \

From DevChiniwala/HeyClara, MIT.

More from DevChiniwala/HeyClara