From 932b2931181181a3a8b75c7dcfb3b6d0954ae1e3 Mon Sep 17 00:00:00 2001
From: Steve Yegge <stevey@sourcegraph.com>
Date: Fri, 31 Oct 2025 12:51:10 -0700
Subject: [PATCH] Document hash-based IDs and hierarchical children
 (bd-a5e2bd80.15)

Amp-Thread-ID: https://ampcode.com/threads/T-afcbc67c-4b83-47d4-8361-7c1ad08906a0
Co-authored-by: Amp <amp@ampcode.com>
---
 AGENTS.md     | 10 +++++++-
 FAQ.md        | 68 +++++++++++++++++++++++++++++++++++++++++++++++++++
 QUICKSTART.md | 30 +++++++++++++++++++++++
 README.md     | 41 +++++++++++++++++++++++++++++++
 4 files changed, 148 insertions(+), 1 deletion(-)

diff --git a/AGENTS.md b/AGENTS.md
index 287c2db9..39a1b281 100644
--- a/AGENTS.md
+++ b/AGENTS.md
@@ -147,6 +147,12 @@ bd create "Issue title" -t bug -p 1 -l bug,critical --json
 # Create multiple issues from markdown file
 bd create -f feature-plan.md --json
 
+# Create epic with hierarchical child tasks
+bd create "Auth System" -t epic -p 1 --json         # Returns: bd-a3f8e9
+bd create "Login UI" -p 1 --json                     # Auto-assigned: bd-a3f8e9.1
+bd create "Backend validation" -p 1 --json           # Auto-assigned: bd-a3f8e9.2
+bd create "Tests" -p 1 --json                        # Auto-assigned: bd-a3f8e9.3
+
 # Update one or more issues
 bd update <id> [<id>...] --status in_progress --json
 bd update <id> [<id>...] --priority 1 --json
@@ -335,9 +341,11 @@ bd daemons killall  # Restart with default (poll) mode
 - `bug` - Something broken that needs fixing
 - `feature` - New functionality
 - `task` - Work item (tests, docs, refactoring)
-- `epic` - Large feature composed of multiple issues
+- `epic` - Large feature composed of multiple issues (supports hierarchical children)
 - `chore` - Maintenance work (dependencies, tooling)
 
+**Hierarchical children:** Epics can have child issues with dotted IDs (e.g., `bd-a3f8e9.1`, `bd-a3f8e9.2`). Children are auto-numbered sequentially. Up to 3 levels of nesting supported. The parent hash ensures unique namespace - no coordination needed between agents working on different epics.
+
 ### Priorities
 
 - `0` - Critical (security, data loss, broken builds)
diff --git a/FAQ.md b/FAQ.md
index 56143a68..3e90b13b 100644
--- a/FAQ.md
+++ b/FAQ.md
@@ -83,6 +83,74 @@ Follow the repo for updates and the path to 1.0!
 
 ## Usage Questions
 
+### Why hash-based IDs? Why not sequential?
+
+**Hash IDs eliminate collisions** when multiple agents or branches create issues concurrently.
+
+**The problem with sequential IDs:**
+```bash
+# Branch A creates bd-10
+git checkout -b feature-auth
+bd create "Add OAuth"  # Sequential ID: bd-10
+
+# Branch B also creates bd-10
+git checkout -b feature-payments
+bd create "Add Stripe"  # Collision! Same sequential ID: bd-10
+
+# Merge conflict!
+git merge feature-auth   # Two different issues, same ID
+```
+
+**Hash IDs solve this:**
+```bash
+# Branch A
+bd create "Add OAuth"  # Hash ID: bd-a1b2 (from random UUID)
+
+# Branch B
+bd create "Add Stripe"  # Hash ID: bd-f14c (different UUID, different hash)
+
+# Clean merge!
+git merge feature-auth   # No collision, different IDs
+```
+
+**Progressive length scaling:**
+- 4 chars (0-500 issues): `bd-a1b2`
+- 5 chars (500-1,500 issues): `bd-f14c3`
+- 6 chars (1,500+ issues): `bd-3e7a5b`
+
+bd automatically extends hash length as your database grows to maintain low collision probability.
+
+### What are hierarchical child IDs?
+
+**Hierarchical IDs** (e.g., `bd-a3f8e9.1`, `bd-a3f8e9.2`) provide human-readable structure for epics and their subtasks.
+
+**Example:**
+```bash
+# Create epic (generates parent hash)
+bd create "Auth System" -t epic -p 1
+# Returns: bd-a3f8e9
+
+# Create children (auto-numbered .1, .2, .3)
+bd create "Login UI" -p 1       # bd-a3f8e9.1
+bd create "Validation" -p 1     # bd-a3f8e9.2
+bd create "Tests" -p 1          # bd-a3f8e9.3
+```
+
+**Benefits:**
+- Parent hash ensures unique namespace (no cross-epic collisions)
+- Sequential child IDs are human-friendly
+- Up to 3 levels of nesting supported
+- Clear visual grouping in issue lists
+
+**When to use:**
+- Epics with multiple related tasks
+- Large features with sub-features
+- Work breakdown structures
+
+**When NOT to use:**
+- Simple one-off tasks (use regular hash IDs)
+- Cross-cutting dependencies (use `bd dep add` instead)
+
 ### Should I run bd init or have my agent do it?
 
 **Either works!** But use the right flag:
diff --git a/QUICKSTART.md b/QUICKSTART.md
index b89c30c6..8ca02f1e 100644
--- a/QUICKSTART.md
+++ b/QUICKSTART.md
@@ -22,6 +22,36 @@ go build -o bd ./cmd/bd
 ./bd list
 ```
 
+**Note:** Issue IDs are hash-based (e.g., `bd-a1b2`, `bd-f14c`) to prevent collisions when multiple agents/branches work concurrently.
+
+## Hierarchical Issues (Epics)
+
+For large features, use hierarchical IDs to organize work:
+
+```bash
+# Create epic (generates parent hash ID)
+./bd create "Auth System" -t epic -p 1
+# Returns: bd-a3f8e9
+
+# Create child tasks (automatically get .1, .2, .3 suffixes)
+./bd create "Design login UI" -p 1       # bd-a3f8e9.1
+./bd create "Backend validation" -p 1    # bd-a3f8e9.2
+./bd create "Integration tests" -p 1     # bd-a3f8e9.3
+
+# View hierarchy
+./bd dep tree bd-a3f8e9
+```
+
+Output:
+```
+🌲 Dependency tree for bd-a3f8e9:
+
+→ bd-a3f8e9: Auth System [epic] [P1] (open)
+  → bd-a3f8e9.1: Design login UI [P1] (open)
+  → bd-a3f8e9.2: Backend validation [P1] (open)
+  → bd-a3f8e9.3: Integration tests [P1] (open)
+```
+
 ## Add Dependencies
 
 ```bash
diff --git a/README.md b/README.md
index 4ea625c2..c1b205ab 100644
--- a/README.md
+++ b/README.md
@@ -271,6 +271,47 @@ bd info
 
 **Note:** Hash IDs require schema version 9+. The `bd migrate` command detects old schemas and upgrades automatically.
 
+### Hierarchical Child IDs
+
+Hash IDs support **hierarchical children** for natural work breakdown structures. Child IDs use dot notation:
+
+```
+bd-a3f8e9      [epic] Auth System
+bd-a3f8e9.1    [task] Design login UI
+bd-a3f8e9.2    [task] Backend validation
+bd-a3f8e9.3    [epic] Password Reset
+bd-a3f8e9.3.1  [task] Email templates
+bd-a3f8e9.3.2  [task] Reset flow tests
+```
+
+**Benefits:**
+- **Collision-free**: Parent hash ensures unique namespace
+- **Human-readable**: Clear parent-child relationships
+- **Flexible depth**: Up to 3 levels of nesting
+- **No coordination needed**: Each epic owns its child ID space
+
+**Common patterns:**
+- 1 level: Epic → tasks (most projects)
+- 2 levels: Epic → features → tasks (large projects)
+- 3 levels: Epic → features → stories → tasks (complex projects)
+
+**Example workflow:**
+```bash
+# Create parent epic (generates hash ID automatically)
+bd create "Auth System" -t epic -p 1
+# Returns: bd-a3f8e9
+
+# Create child tasks
+bd create "Design login UI" -p 1       # Auto-assigned: bd-a3f8e9.1
+bd create "Backend validation" -p 1    # Auto-assigned: bd-a3f8e9.2
+
+# Create nested epic with its own children
+bd create "Password Reset" -t epic -p 1  # Auto-assigned: bd-a3f8e9.3
+bd create "Email templates" -p 1          # Auto-assigned: bd-a3f8e9.3.1
+```
+
+**Note:** Child IDs are automatically assigned sequentially within each parent's namespace. No need to specify parent manually - bd tracks context from git branch/working directory.
+
 ## Usage
 
 ### Health Check