Simple task tracking for LLM sessions - ownership-based workflow for multi-agent coordination

version
0.2.1
GitHub stars
11

Install

/plugin install ba@ba

Run it inside Claude Code after adding the marketplace with /plugin marketplace add open-horizon-labs/ba.

Contents

Discovered from source

Commands 4

Initialize ba

Initialize ba task tracking for this project.

Step 1: Check current state

  • Check if .ba/ already exists - if so, tell user it's already initialized and show status
  • Check if ba binary is available (command -v ba) - if yes, skip to Step 3

Step 2: Install ba binary

Detect available package managers:

  • Homebrew: command -v brew
  • Cargo: command -v cargo OR test -f ~/.cargo/bin/cargo

Offer installation based on what's available:

If Homebrew available (preferred for macOS):

brew install cloud-atlas-ai/ba/ba

If Cargo available:

cargo install ba
# or if cargo not in PATH:
~/.cargo/bin/cargo install ba

If neither available, offer to install a package manager:

  • Install Homebrew (recommended for macOS):

    /bin/bash -c "$(curl -fsSL https://raw.githubusercontent.com/Homebrew/install/HEAD/install.sh)"
    

    Then: brew install cloud-atlas-ai/ba/ba

  • Install Rust (cross-platform):

    curl --proto '=https' --tlsv1.2 -sSf https://sh.rustup.rs | sh
    

    Then restart shell and: cargo install ba

For local development (if user specifies a path):

cargo install --path /path/to/ba
# or: ~/.cargo/bin/cargo install --path /path/to/ba

Step 3: Initialize project

After ba binary is available, run:

ba init

This creates .ba/ directory with:

  • config.json - Project config (version, ID prefix)
  • issues.jsonl - Issue storage

Step 4: Update AGENTS.md

Check if AGENTS.md exists in the project root. If not, create it with:

# AGENTS.md

This file provides guidance to Claude Code when working with code in this repository.

## Project Overview

[Add project-specific overview here]

## ba Task Tracking

This project uses ba for task tracking. You have the `$ba` skill available in Codex mode.

**Core workflow:**
1. Check ready queue: `ba ready` - shows open, unblocked issues
2. Claim an issue: `ba claim <id> --session $SESSION_ID`
3. Work on the issue
4. Complete: `ba finish <id>`
5. Or release: `ba release <id>` if not done

**Quick reference:**
- `ba list` - Show all open issues (excludes closed)
- `ba list --all` - Include closed issues
- `ba show <id>` - Show issue details
- `ba mine --session $SESSION_ID` - Show your claimed issues
- `ba create "title" -t task -p 1` - Create new issue
- `ba comment <id> "message"` - Add comment

**Ownership-based state machine:**
- `open` → claim → `in_progress` (you own it)
- `in_progress` → finish → `closed`
- `in_progress` → release → `open` (back to pool)
- Claiming a closed issue reopens it automatically

**Issue types:** task, epic, refactor, spike
**Priorities:** 0 (critical) to 4 (backlog), default 2

See README.md for full details.

If AGENTS.md already exists, append the ba section:

# Quoted heredoc prevents $SESSION_ID expansion in AGENTS.md
cat >> AGENTS.md << 'EOF'

## ba Task Tracking

This project uses ba for task tracking. You have the `$ba` skill available in Codex mode.

**Core workflow:**
1. Check ready queue: `ba ready` - shows open, unblocked issues
2. Claim an issue: `ba claim <id> --session $SESSION_ID`
3. Work on the issue
4. Complete: `ba finish <id>`
5. Or release: `ba release <id>` if not done

**Quick reference:**
- `ba list` - Show all open issues (excludes closed)
- `ba list --all` - Include closed issues
- `ba show <id>` - Show issue details
- `ba mine --session $SESSION_ID` - Show your claimed issues
- `ba create "title" -t task -p 1` - Create new issue
- `ba comment <id> "message"` - Add comment

**Ownership-based state machine:**
- `open` → claim → `in_progress` (you own it)
- `in_progress` → finish → `closed`
- `in_progress` → release → `open` (back to pool)
- Claiming a closed issue reopens it automatically

**Issue types:** task, epic, refactor, spike
**Priorities:** 0 (critical) to 4 (backlog), default 2

See README.md for full details.
EOF

Step 5: Install Codex skill

Install the $ba Codex skill files to enable ba commands in Claude Code sessions:

# Create skill directory
SKILL_DIR="$HOME/.codex/skills/ba"
mkdir -p "$SKILL_DIR"

echo "Installing ba Codex skill..."
if curl -fsSL -o "$SKILL_DIR/SKILL.md" \
  "https://raw.githubusercontent.com/cloud-atlas-ai/ba/master/codex-skill/SKILL.md" && \
   curl -fsSL -o "$SKILL_DIR/AGENTS.md.snippet" \
  "https://raw.githubusercontent.com/cloud-atlas-ai/ba/master/codex-skill/AGENTS.md.snippet"; then
  echo "✓ Codex skill installed to $SKILL_DIR"
  echo ""
  echo "The \$ba skill is now available for:"
  echo "  \$ba ready    - Show available issues"
  echo "  \$ba claim    - Claim an issue"
  echo "  \$ba mine     - Show your claimed issues"
  echo "  \$ba finish   - Complete an issue"
else
  echo "⚠️  Failed to download Codex skill files"
  echo "You can manually install from: https://github.com/cloud-atlas-ai/ba/tree/master/codex-skill"
fi

Step 6: Verify SESSION_ID

Check if SESSION_ID is available for ownership operations:

if [ -z "$SESSION_ID" ]; then
  echo ""
  echo "⚠️  SESSION_ID not set"
  echo "Claude Code provides this automatically in active sessions."
  echo "To set manually: export SESSION_ID=\$(uuidgen | tr '[:upper:]' '[:lower:]')"
else
  echo ""
  echo "✓ SESSION_ID is set: $SESSION_ID"
fi

Step 7: Confirm

Tell user:

✓ ba initialized and ready

Created .ba/ directory with project config
Installed $ba Codex skill to ~/.codex/skills/ba/
Added ba guidance to AGENTS.md

Quick start:
  ba create "Your first task" -t task
  ba list
  ba claim <id> --session $SESSION_ID

Use $ba commands in Codex mode:
  $ba ready, $ba claim <id>, $ba finish <id>

Be concise. Detect what's available, offer appropriate options, guide user through setup.

ba New

Guided task creation with proper scoping and specification.

Goal

Help users create well-specified, actionable ba tasks. Guide them from a rough idea to one or more properly scoped tasks.

Step 1: Get initial input

Ask the user what they want to accomplish:

What do you want to accomplish? Describe the task or goal in a few words.

If user provides something vague like "fix the thing" or "improve performance", probe for specifics:

  • What specifically is broken or needs improvement?
  • What behavior should change?
  • What does success look like?

Step 2: Check for duplicates

Before creating, search existing tasks for similar work:

ba list --all --json | jq -r '.[] | "\(.id): \(.title) (\(.status))"'

Look for tasks with:

  • Similar keywords in the title
  • Related subject matter
  • Same general area of the codebase

If a potential duplicate is found:

I found an existing task that might be related:
  <id>: <title> (<status>)

Is this the same work, or something different?

If same work:

  • If closed: Ask if user wants to reopen it
  • If open/in_progress: Point them to it, no new task needed

If different work: Proceed with creation. Consider adding a comment mentioning the related task ID for context.

Step 3: Assess scope

Evaluate if the task is properly scoped. A well-scoped task:

  • Can be completed in a single focused session
  • Has clear acceptance criteria
  • Doesn't require breaking into subtasks

Signs of oversized scope:

  • Multiple unrelated changes
  • "And also..." in the description
  • Would touch many different areas of code
  • Contains multiple acceptance criteria that could stand alone

If scope is too large:

Suggest breaking down into smaller tasks:

This sounds like it could be multiple tasks. I see:
1. [First discrete piece of work]
2. [Second discrete piece of work]
3. [Third discrete piece of work]

Should I create these as separate tasks? They can be linked as dependencies if needed.

Step 4: Refine the title

Help craft an actionable title. Good titles:

  • Start with a verb (Add, Fix, Update, Remove, Implement, Refactor)
  • Are specific enough to understand without context
  • Fit in ~10 words

Transform vague titles:

  • "auth stuff" → "Add JWT token refresh on expiration"
  • "fix bug" → "Fix login redirect loop when session expires"
  • "improve perf" → "Add caching to database queries in search endpoint"

Propose a refined title and confirm:

How about: "[refined title]"

Does this capture what you want to do?

Step 5: Determine type

Based on the work described, recommend a type:

  • task - Building something new or changing behavior
  • refactor - Improving code without changing behavior
  • spike - Research or investigation, time-boxed exploration
  • epic - Container for related tasks (only if creating multiple)
This sounds like a [type]. [Brief explanation of why]

Step 6: Add context (optional)

For non-trivial tasks, ask if there's additional context:

Any additional context to capture? For example:
- Acceptance criteria (what does "done" look like?)
- Technical constraints or approaches to consider
- Related files or areas of code

If user provides context, it becomes a comment on the created task.

Step 7: Set priority

Offer priority options:

Priority?
- 0: Critical - drop everything
- 1: High - do soon
- 2: Medium - normal queue (default)
- 3: Low - when you get to it
- 4: Backlog - someday/maybe

Default to P2 if user doesn't specify.

Step 8: Handle dependencies (if multiple tasks)

If creating multiple tasks, ask about dependencies:

Should any of these tasks block others?
For example: Task 2 depends on Task 1 being done first.

Step 9: Create task(s)

Execute the creation:

# Single task
ba create "Title here" -t task -p 2

# With comment for context
ba create "Title here" -t task -p 2
ba comment <id> "Additional context here"

# Multiple tasks with dependencies
ba create "First task" -t task -p 2
ba create "Second task (depends on first)" -t task -p 2
ba block <second-id> <first-id>

Step 10: Confirm

Show what was created:

Created:
  <id>: Title (type, priority)

Ready to claim with:
  ba claim <id> --session $SESSION

Or for multiple tasks:

Created 3 tasks:
  <id1>: First task (task, P2) - ready
  <id2>: Second task (task, P2) - blocked by <id1>
  <id3>: Third task (task, P2) - blocked by <id2>

Task tree:
  <id1> → <id2> → <id3>

Start with:
  ba claim <id1> --session $SESSION

Quick mode

If user provides a clear, well-specified task upfront, skip the refinement:

User: Create a task to add input validation to the signup form that rejects emails without @ symbol

This is already:

  • Actionable (add validation)
  • Specific (signup form, email field, @ symbol check)
  • Properly scoped (single focused change)

Just confirm type and priority, then create.

Examples

Example 1: Vague input

User: I need to fix auth
Claude: What specifically is broken with authentication?
        - Login not working?
        - Token expiration issues?
        - Permission checks failing?

User: Oh, the JWT tokens expire and users get logged out

Claude: Got it. How about: "Add JWT token refresh before expiration"
        This is a task (adding new behavior). Priority?

User: High, it's annoying users

Claude: Created:
  ab-x7k2: Add JWT token refresh before expiration (task, P1)

  Ready to claim: ba claim ab-x7k2 --session $SESSION

Example 2: Oversized scope

User: I want to add a dashboard

Claude: A dashboard could be quite broad. What should it show?

User: User stats, recent activity, and admin controls

Claude: This sounds like 3 separate pieces:
  1. "Add user statistics panel to dashboard"
  2. "Add recent activity feed to dashboard"
  3. "Add admin control panel to dashboard"

Should I create these as separate tasks? They can work independently.

User: Yes, and admin controls need the stats first

Claude: Created 3 tasks:
  ab-y1a2: Add user statistics panel to dashboard (task, P2) - ready
  ab-z3b4: Add recent activity feed to dashboard (task, P2) - ready
  ab-c5d6: Add admin control panel to dashboard (task, P2) - blocked by ab-y1a2

Start with either ab-y1a2 or ab-z3b4 (both ready).

Example 3: Quick create

User: Task to update the README with new installation instructions for ARM64

Claude: Clear and specific. Creating:
  "Update README with ARM64 installation instructions" (task, P2)

  ab-m7n8 created. Ready to claim.

Keep the conversation natural. Don't be overly formal or robotic. The goal is helping users think through their tasks, not running them through a rigid form.

ba Quick Start

Show a quick start guide for using ba in this session.

Display Guide

Show this concise reference:

ba - Task Tracking Quick Start
==============================

Core Workflow:
  ba ready                            # See available work
  ba claim <id> --session $SESSION_ID # Take ownership
  ba show <id>                        # Check details
  ba finish <id>                      # Complete work
  ba release <id>                     # Abandon work

Browse:
  ba list                             # All open issues
  ba list --all                       # Include closed
  ba mine --session $SESSION_ID       # Your claimed issues

Create:
  ba create "title" -t task -p 1      # New issue
  ba comment <id> "msg" --author $SESSION_ID

Dependencies:
  ba block <id> <blocker-id>          # Mark as blocked
  ba tree <id>                        # Visualize deps

Ownership State Machine:
  open → claim → in_progress → finish → closed
                      ↓
                  release
                      ↓
                    open

Issue Types:
  task      - General work (default)
  epic      - Grouping container
  refactor  - Improve existing code
  spike     - Research/investigation

Priorities:
  0 - Critical    1 - High    2 - Medium (default)
  3 - Low         4 - Backlog

Session ID:
  Use --session $SESSION_ID for claim/mine/comment
  This identifies you in multi-agent workflows

Storage:
  .ba/issues.jsonl  - One issue per line (git-friendly)
  .ba/config.json   - Project configuration

More info: ba --help or README.md

Check if initialized

If .ba/ doesn't exist, suggest:

ba not initialized yet. Run:
  /ba init

Keep it concise. This is a reference card, not a tutorial.

ba Status

Show current ba status for this project.

Check if initialized

First, check if ba is initialized:

if [ -d .ba ]; then
  echo "✓ ba is initialized"
else
  echo "✗ ba not initialized - run /ba init"
  exit 0
fi

Show configuration

cat .ba/config.json

Displays:

  • Version
  • ID prefix (derived from project path)

Show issue counts

echo "Issue counts:"
ba list --json | jq '. | length' | xargs -I {} echo "  Open: {}"
ba list --all --json | jq '[.[] | select(.status == "closed")] | length' | xargs -I {} echo "  Closed: {}"
ba list --all --json | jq '[.[] | select(.status == "in_progress")] | length' | xargs -I {} echo "  In Progress: {}"

Show ready queue

echo ""
echo "Ready to work:"
ba ready

Check your claimed issues

If $SESSION_ID is available:

echo ""
echo "Your claimed issues:"
ba mine --session "$SESSION_ID"

Summary format

Present information concisely:

✓ ba initialized

Project: ab (prefix)
Version: 2

Issues:
  Open: 12
  In Progress: 3
  Closed: 45

Ready to work: 8 issues

Your claimed: 2 issues
  ab-x7k2 (P1): Fix auth bug
  ab-y8m3 (P2): Add dashboard

Be concise. Show what matters. If not initialized, suggest /ba init.

Sponsors

Details

Marketplace
open-horizon-labs/ba
Source
plugin
Author
Cloud Atlas AI
Category
Community