What I Do

• Initialize git repository and configure bd properly

• Create a new product epic as the parent container

• Generate a chain of related issues for product development phases

• Set up proper dependencies between issues (research → design → development → testing → launch)

• Create milestone markers for tracking progress

• Establish a structured workflow for the product lifecycle

When to Use Me

⚠️ CRITICAL: Only use this skill for NEW projects without an existing .beads/ directory!

Test first: Run ls -la .beads/ — if you see issues.jsonl , use bd-modify-product-description-and-tasks instead.

Use this skill when you need to:

• Kick off a new product initiative (no existing .beads/ folder)

• Set up a structured project with clear phases from scratch

• Create a product roadmap with dependent tasks for a fresh project

• Establish a complete development workflow on a new codebase

• Onboard a new product with proper issue tracking (first-time setup)

Git + JSONL: How bd Works

No database servers. No cloud APIs. Just Git + JSONL.

All issues live in .beads/issues.jsonl — a simple JSON Lines file that git tracks like any other code. This means:

• Pull → see updates: git pull brings down everyone's issue changes

• Push → share yours: git push publishes your issue updates to the team

• Merge conflicts are possible: If two people edit the same issue simultaneously, you'll get a classic git merge conflict (just like with code)

• Hash IDs reduce conflicts: Every issue has a unique hash ID, making simultaneous edits on different issues seamless

This is version control for your project management — fully distributed, offline-capable, and conflict-aware.

bd Commands to Use

Check for Existing Project

BEFORE starting: Test if .beads/ already exists:

ls -la .beads/ 2>/dev/null || echo "No .beads/ directory found - safe to proceed"

If .beads/ already exists with issues.jsonl and config.yaml :

• STOP — This project already has an issue tracker configured

• Use bd-modify-product-description-and-tasks skill instead to add/modify issues to the existing project

• This skill is for NEW projects only

Initialize Repository and Setup

Step 1: Initialize git repository first (required for bd)

git init

Step 2: Initialize bd with a project prefix

bd init --prefix <project-name>

Step 3: Enable no-db mode (CRITICAL - makes JSONL the source of truth)

Edit .beads/config.yaml and set: no-db: true

Step 4: If you see "LEGACY DATABASE" warnings, migrate the repo ID

bd migrate --update-repo-id

CRITICAL: Enable no-db mode in .beads/config.yaml

Edit .beads/config.yaml and add:

Use no-db mode: load from JSONL, no SQLite, write back after each command

When true, bd will use .beads/issues.jsonl as the source of truth

instead of SQLite database

no-db: true

This makes .beads/issues.jsonl the source of truth — every bd command reads from and writes directly to the JSONL file. No SQLite database. Full git tracking of every issue change.

Verify: Your .beads/ folder should only contain 3 files:

$ ls -la .beads/ config.yaml # Your configuration with no-db: true issues.jsonl # All issues stored as JSON Lines (git-tracked) metadata.json # Project metadata (prefix, repo binding, etc.)

No beads.db file! If you see a .beads/beads.db file, you haven't enabled no-db mode correctly. SQLite database files should not exist — all data lives in JSONL.

Important: Always run git init before bd init to avoid repository ID warnings. If warnings persist after creation, run bd migrate --update-repo-id .

Initialize Product Epic

bd create "<Product Name>" --type epic --description "<product vision and scope>"

Creates the parent epic that will contain all related issues.

Create Issue Chain

bd create "Research & Discovery" --type task --description "<research requirements>" -p <epic-id> bd create "Project Setup & Dependencies" --type task --description "<setup requirements>" -p <epic-id> bd create "Design & Architecture" --type task --description "<design scope>" -p <epic-id> bd create "Core Implementation" --type task --description "<development work>" -p <epic-id> bd create "Testing & QA" --type task --description "<testing scope>" -p <epic-id> bd create "Documentation" --type task --description "<docs needed>" -p <epic-id> bd create "Release & Deploy" --type task --description "<deployment steps>" -p <epic-id>

Creates the core development chain under the epic.

Chain Dependencies

bd dep add <setup-id> <research-id> bd dep add <design-id> <research-id> bd dep add <implementation-id> <design-id> bd dep add <testing-id> <implementation-id> bd dep add <docs-id> <implementation-id> bd dep add <release-id> <testing-id> bd dep add <release-id> <docs-id>

Links issues in a sequential dependency chain.

Set Issue Types and Labels

bd label add <issue-id> phase-1 bd label add <issue-id> milestone bd label add <issue-id> critical-path

Tags issues for filtering and organization.

View Product Structure

bd epic show <epic-id> bd graph cat .beads/beads.jsonl | head -20

Shows the product structure and dependencies.

Check Ready Work

bd ready

Shows what issues are ready to work on (no blockers).

Complete Workflow for Creating New Product

• Check for existing project: Run ls -la .beads/ — if it exists, use bd-modify-product-description-and-tasks skill instead

• Initialize Git: Run git init to create a git repository

• Initialize bd: Run bd init --prefix <name> to set up the database

• Enable no-db mode: Edit .beads/config.yaml and set no-db: true — this makes JSONL the source of truth

• Fix Warnings: If you see "LEGACY DATABASE" warnings, run bd migrate --update-repo-id

• Create the Epic: Use bd create with --type epic to establish the product container

• Create Issues: Use bd create with -p <epic-id> to create child issues

• Chain Dependencies: Use bd dep add to link issues in order

• Add Labels: Use bd label add for categorization and filtering

• Verify Structure: Use bd status to confirm everything is set up correctly

• Verify no-db mode: Check that .beads/ only contains config.yaml , issues.jsonl , and metadata.json (no beads.db !)

Typical Product Issue Chain

Epic: Product X Development ├── Task: Research & Discovery [OPEN] │ └── Ready to start (no dependencies) ├── Task: Project Setup & Dependencies [OPEN] │ └── Can run parallel with Research ├── Task: Design & Architecture [OPEN] │ └── Dep: Research & Discovery ├── Task: Core Implementation [OPEN] │ └── Dep: Project Setup, Design & Architecture ├── Task: Testing & QA [OPEN] │ └── Dep: Core Implementation ├── Task: Documentation [OPEN] │ └── Dep: Core Implementation └── Task: Release & Deploy [OPEN] └── Dep: Testing & QA, Documentation

Best Practices

• Git First: Always initialize git before bd to avoid repository ID warnings

• Fix Warnings Early: Run bd migrate --update-repo-id if you see legacy database warnings

• Start with Research: Always begin with discovery before committing to solutions

• Sequential Dependencies: Link issues so work flows naturally from one phase to the next

• Parallel Work: Identify which tasks can run in parallel (e.g., setup with research, docs with testing)

• Critical Path: Label the main development line for priority focus

• Milestone Labels: Use labels to mark major checkpoints

• Keep It Lean: Don't over-engineer the chain - focus on real dependencies

Troubleshooting

Project Already Has .beads/ Directory

If you see .beads/ with issues.jsonl already exists:

$ ls -la .beads/ config.yaml issues.jsonl metadata.json

Solution: Use bd-modify-product-description-and-tasks skill instead. This skill is for creating new projects only. The modify skill will help you add to the existing issue tracker.

"LEGACY DATABASE DETECTED" Warning

If you see this warning:

bd migrate --update-repo-id

This binds the database to your git repository and prevents the warnings.

Repository Not Initialized

If bd shows "No git repository initialized":

git init bd migrate --update-repo-id

Quick Command Reference

Initialize properly:

git init bd init --prefix my-project

CRITICAL: Edit .beads/config.yaml and set no-db: true

echo "no-db: true" >> .beads/config.yaml bd migrate --update-repo-id # If needed

Verify: Should only see config.yaml, issues.jsonl, metadata.json

ls -la .beads/

Check what's ready to work on:

bd ready

View dependency graph:

bd graph

See blocked issues:

bd blocked

List all issues in epic:

bd epic show <epic-id>

Show product status:

bd status