Beads Task Tracking

Beads is a git-based task tracking system integrated with AIKit for managing development work with quality gates and workflow enforcement.

What is Beads?

Beads (bd) is a command-line tool that tracks development tasks as files in a .beads/ directory. Each task is a markdown file with:

Task metadata (title, description, type)
Status tracking (todo, in-progress, completed, blocked)
Git integration (syncs with git commits)
Quality gates enforcement
Custom fields and metadata

Why Beads?

Git-based: All tasks are tracked in version control
No external services: No need for Jira, Trello, GitHub Projects
Simple: Tasks are just markdown files
Flexible: Customize with frontmatter and metadata
AIKit Integrated: Quality gates, status tracking, command hooks

Getting Started

Automatic Setup (Recommended)

Beads is automatically initialized when you run aikit init:

cd your-project
aikit init

This creates a fully functional .beads/ directory with:

.beads/config.yaml - Beads configuration
.beads/metadata.json - Database settings
.beads/.gitignore - Git ignore patterns
.beads/.local_version - Version tracking
.beads/README.md - Documentation
Git hooks for automatic syncing

No manual setup required! The workspace is ready to use immediately with OpenCode and Claude Code.

Optional: Install Beads CLI

For advanced Beads functionality beyond what AIKit provides, you can optionally install the Beads CLI:

# Via npm
npm install -g beads

# Verify installation
bd --version

Note: The Beads CLI is optional. AIKit provides full Beads functionality through slash commands and MCP tools. Only install the CLI if you want additional command-line features.

Task Structure

Each task is a markdown file in .beads/ directory:

---
id: "001"
title: "Add user authentication"
status: "in-progress"
type: "feature"
priority: "high"
created: "2026-01-02T14:30:00Z"
updated: "2026-01-02T15:45:00Z"
assignee: "developer"
labels: ["authentication", "security", "jwt"]
---

# Add user authentication

## Description

Implement OAuth 2.0 authentication flow with JWT tokens for user login and session management.

## Requirements

- [x] User can log in with email/password
- [x] Session is managed via JWT tokens
- [ ] Refresh token mechanism
- [ ] Token validation middleware
- [ ] Logout functionality

## Implementation Notes

- Use `jsonwebtoken` library for JWT
- Store refresh tokens in httpOnly cookies
- Token expiration: 1 hour (access), 7 days (refresh)

## Quality Gates

- [x] Typecheck passes
- [x] All tests pass
- [x] Linting passes
- [x] Build succeeds

## Verification

- [ ] Manual testing completed
- [ ] Code review passed
- [ ] Security audit completed

## References

- [OAuth 2.0 specification](https://oauth.net/2/)
- [JWT best practices](https://tools.ietf.org/html/rfc8725)

Task Types

Type	Description	Use Case
`feature`	New feature implementation	Adding new functionality
`bug`	Bug fix	Fixing reported issues
`pattern`	Code pattern or best practice	Documenting architectural decisions
`decision`	Technical decision	Recording architectural choices
`knowledge`	Knowledge base entry	Documenting learnings
`refactor`	Code refactoring	Improving existing code
`test`	Test improvement	Adding or improving tests
`docs`	Documentation	Writing or updating docs

Task Status

Status	Description	Action
`todo`	Not started	Ready to work on
`in-progress`	Currently working	Active task
`completed`	Finished	Quality gates passed
`blocked`	Waiting on something	Depends on other task
`cancelled`	Won't be done	Task cancelled

Beads Commands

Create Task (via AIKit)

/create Add user authentication

This creates a new task using AIKit's integrated Beads functionality:

AIKit automatically:

Generates unique task ID
Creates task file in .beads/
Sets initial status to "in-progress"
Links to current session

Example:

/create "Add user authentication" --type feature --priority high

Create Task (via Beads CLI)

If you have the Beads CLI installed:

bd create "Add user authentication"

Creates new task file: .beads/bead-001.md

Tip: Use AIKit's /create command for better integration with sessions and workflows.

Options:

bd create "Task title" \
  --description "Detailed description" \
  --type feature \
  --priority high \
  --assignee developer

List Tasks

bd list

List all tasks with status.

Output:

001 Add user authentication          [in-progress] feature    high
002 Fix login bug                   [todo]        bug        medium
003 Implement refresh token          [blocked]      feature    high

Filter by status:

bd list --status in-progress
bd list --status todo
bd list --status blocked

Filter by type:

bd list --type feature
bd list --type bug

Filter by priority:

bd list --priority high
bd list --priority medium

Show Task Details

bd show 001

Display full task details.

Or show by title:

bd show "user authentication"

Update Task Status

bd update 001 --status in-progress

Update task status.

Available statuses:

bd update 001 --status todo
bd update 001 --status in-progress
bd update 001 --status completed
bd update 001 --status blocked
bd update 001 --status cancelled

Update Task Type

bd update 001 --type feature

Update task type.

Update Task Priority

bd update 001 --priority high

Update task priority.

Available priorities:

bd update 001 --priority critical
bd update 001 --priority high
bd update 001 --priority medium
bd update 001 --priority low

Complete Task

bd complete 001

Mark task as completed after running quality gates.

Quality gates run:

npm run typecheck - No type errors
npm run test - All tests pass
npm run lint - No linting errors
npm run build - Build succeeds

If all gates pass, task is marked completed.

If any gate fails, task remains in current state and reports which gate failed.

Delete Task

bd delete 001

Delete a task file.

Warning: This cannot be undone.

Sync with Git

bd sync

Synchronize tasks with git:

Stages all .beads/ changes
Creates commit: "Update task tracking"
Pushes to remote

Interactive Commands

Ready: Find available work

bd ready

Lists tasks ready to work on (todo, unblocked).

Onboard: Initialize new project

bd onboard

Guided setup for new projects.

AIKit Integration

AIKit Commands

AIKit provides Beads commands via slash commands:

/create Add user authentication
# Same as: bd create "Add user authentication"

/show 001
# Same as: bd show 001

/list --status in-progress
# Same as: bd list --status in-progress

/update 001 --status completed
# Same as: bd update 001 --status completed

/complete 001
# Same as: bd complete 001

MCP Tools

When using AIKit via MCP, Beads tools are available:

# Create task
> bead_create("Add user authentication", "Implement OAuth 2.0")

# Update status
> bead_update_status("001", "in-progress")

# Complete with quality gates
> bead_complete("001")

# List tasks
> bead_list()
> bead_list({status: "in-progress"})

Quality Gates

AIKit automatically runs quality gates when completing tasks via /complete or /finish:

/create Add user authentication
/implement
# ... implementation ...
/finish
# Runs quality gates:
#   ✓ npm run typecheck
#   ✓ npm run test
#   ✓ npm run lint
#   ✓ npm run build
# Task marked as completed

Task Metadata

Custom Frontmatter

Add custom fields to task frontmatter:

---
id: "001"
title: "Add user authentication"
status: "in-progress"
type: "feature"
priority: "high"

# Custom fields
complexity: "medium"
estimated: "4h"
storyPoints: 5
related: ["002", "003"]
tags: ["authentication", "security", "jwt"]
parent: "000"
---

# Task content

Required Fields

Field	Type	Required	Description
`id`	string	Yes	Unique task identifier (auto-generated)
`title`	string	Yes	Task title
`status`	string	Yes	Task status
`type`	string	Yes	Task type
`created`	date	Yes	Creation timestamp (auto-generated)
`updated`	date	Yes	Last update timestamp (auto-generated)

Optional Fields

Field	Type	Default	Description
`priority`	string	`medium`	Task priority
`description`	string	Title	Detailed description
`assignee`	string	None	Who is working on this
`labels`	array	`[]`	Task labels/tags
`estimated`	string	None	Time estimate
`complexity`	string	None	Task complexity
`storyPoints`	number	None	Story points
`related`	array	`[]`	Related task IDs
`parent`	string	None	Parent task ID

Workflow Examples

Feature Development

# 1. Create task
/create Add user authentication

# 2. Plan implementation
/plan user authentication system

# 3. Implement with TDD
/test-driven-development
/implement

# 4. Update progress
/update 001 --status in-progress

# 5. Complete with quality gates
/finish

Bug Fix

# 1. Create bug task
bd create "Fix login timeout bug" --type bug --priority critical

# 2. Debug with skill
/systematic-debugging

# 3. Implement fix
/implement

# 4. Verify fix
npm run test

# 5. Complete
bd complete 001

Refactoring

# 1. Create refactor task
bd create "Refactor auth middleware" --type refactor --priority medium

# 2. Use refactoring skill
/refactoring

# 3. Implement changes
/implement

# 4. Ensure tests pass
npm run test

# 5. Complete
bd complete 002

Pattern Documentation

# 1. Create pattern task
bd create "JWT authentication pattern" --type pattern --priority low

# 2. Document pattern
# Edit .beads/003-jwt-authentication-pattern.md
# Add pattern details, examples, best practices

# 3. Complete (no quality gates)
bd complete 003

Task Dependencies

Parent-Child Relationships

Create hierarchical tasks:

# Parent task
bd create "Implement user authentication"

# Child tasks
bd create "Implement login form" --parent "001"
bd create "Implement JWT middleware" --parent "001"
bd create "Implement refresh token" --parent "001"

Link related tasks:

# Create related tasks
bd create "Implement password reset" --related ["001"]
bd create "Implement 2FA" --related ["001", "002"]

Blocked Tasks

When a task depends on another:

# Task 002 is blocked by 001
bd update 002 --status blocked
# Add note: Waiting for task 001 to complete

# When 001 completes
bd complete 001
# Unblocks 002
bd update 002 --status in-progress

Quality Gates

Default Quality Gates

AIKit runs these gates when completing tasks:

Gate	Command	Purpose
Typecheck	`npm run typecheck`	No TypeScript errors
Test	`npm run test`	All tests pass
Lint	`npm run lint`	No linting errors
Build	`npm run build`	Build succeeds

Custom Quality Gates

Configure custom quality gates in .aikit/aikit.json:

{
  "beads": {
    "qualityGates": [
      {
        "name": "typecheck",
        "command": "npm run typecheck",
        "required": true
      },
      {
        "name": "test",
        "command": "npm run test",
        "required": true
      },
      {
        "name": "e2e",
        "command": "npm run test:e2e",
        "required": false
      }
    ]
  }
}

Skipping Quality Gates

For documentation or pattern tasks:

bd complete 003 --skip-gates

Warning: Only skip for non-code tasks.

Git Integration

Automatic Syncing

AIKit automatically syncs with git when:

Task is created
Task status changes
Task is completed
Task is deleted

Manual Syncing

bd sync

Manually commit task changes.

Git Hooks

Add git hooks for task tracking:

Pre-commit hook:

# .git/hooks/pre-commit
#!/bin/bash
# Check if task is in-progress before committing
bd list --status in-progress
if [ $? -eq 0 ]; then
  echo "Warning: Committing with task in-progress"
fi

Best Practices

Task Creation

✅ DO:

Write clear, descriptive titles
Include detailed requirements
Set appropriate type and priority
Break large tasks into smaller ones
Add labels for filtering

❌ DON'T:

Create vague tasks ("fix stuff")
Mix multiple features in one task
Skip type or priority
Create tasks larger than 4 hours

Task Updates

✅ DO:

Update status regularly
Add progress notes
Link related tasks
Mark blockers early

❌ DON'T:

Leave tasks in limbo
Skip quality gates for code tasks
Forget to update after work

Task Completion

✅ DO:

Run all quality gates
Verify implementation
Update related tasks
Document learnings

❌ DON'T:

Skip gates to save time
Complete without testing
Leave related tasks blocked

Troubleshooting

"Task not found"

bd show 999
# Error: Task '999' does not exist

# List available tasks
bd list

# Use correct ID or title
bd show 001

"Quality gate failed"

bd complete 001
# Error: Quality gate failed - npm run test

# Check test failures
npm run test

# Fix issues
# ... implementation ...

# Retry completion
bd complete 001

"Git sync failed"

bd sync
# Error: Nothing to commit or no changes added

# Check git status
git status

# Staging files if needed
git add .beads/

# Try again
bd sync

Next Steps

Beads Workflow - Complete workflow with diagram
Features - All AIKit features
MCP Server - OpenCode integration
Commands Reference - AIKit commands

What is Beads?

Getting Started

Automatic Setup (Recommended)

Optional: Install Beads CLI

Task Structure

Task Types

Task Status

Beads Commands

Create Task (via AIKit)

Create Task (via Beads CLI)

List Tasks

Show Task Details

Update Task Status

Update Task Type

Update Task Priority

Complete Task

Delete Task

Sync with Git

Interactive Commands

AIKit Integration

AIKit Commands

MCP Tools

Quality Gates

Task Metadata

Custom Frontmatter

Required Fields

Optional Fields

Workflow Examples

Feature Development

Bug Fix

Refactoring

Pattern Documentation

Task Dependencies

Parent-Child Relationships

Related Tasks

Blocked Tasks

Quality Gates

Default Quality Gates

Custom Quality Gates

Skipping Quality Gates

Git Integration

Automatic Syncing

Manual Syncing

Git Hooks

Best Practices

Task Creation

Task Updates

Task Completion

Troubleshooting

"Task not found"

"Quality gate failed"

"Git sync failed"

Next Steps

Related Links