title: Add template support for issue creation

description:
Support creating issues from predefined templates to streamline common workflows like epics, bug reports, or feature proposals.

Example usage:
  bd create --from-template epic "Phase 3 Features"
  bd create --from-template bug "Login failure"
  bd template list
  bd template create epic

Templates should include:
- Pre-filled description structure
- Suggested priority and type
- Common labels
- Design/acceptance criteria sections

Implementation notes:
- Store templates in .beads/templates/ directory
- Support YAML or JSON format
- Ship with built-in templates (epic, bug, feature)
- Allow custom project-specific templates

status: closed

issue_type: feature


title: Add comprehensive tests for config.yaml issue-prefix migration

description:
The GH #209 config.yaml migration lacks test coverage:

Missing tests:
- config.SetIssuePrefix() edge cases (empty file, comments, malformed YAML)
- config.GetIssuePrefix() with various config states
- MigrateConfigToYAML() automatic migration logic
- bd init writing to config.yaml instead of DB
- bd migrate DB→config.yaml migration path

Test scenarios needed:
1. SetIssuePrefix with empty config.yaml
2. SetIssuePrefix with existing config.yaml (preserves other settings)
3. SetIssuePrefix with commented issue-prefix line
4. SetIssuePrefix atomic write (temp file cleanup)
5. GetIssuePrefix fallback behavior
6. MigrateConfigToYAML when config.yaml missing prefix but DB has it
7. MigrateConfigToYAML when both missing (detect from issues)
8. MigrateConfigToYAML when config.yaml already has prefix (no-op)
9. Integration test: fresh bd init writes to config.yaml only
10. Integration test: upgrade from v0.21 DB migrates to config.yaml

Priority 1 because this is a user-facing migration affecting all users upgrading to v0.22.

issue_type: task


title: Override test

description:
## Overview

[Describe the high-level goal and scope of this epic]

## Success Criteria

- [ ] Criteria 1
- [ ] Criteria 2
- [ ] Criteria 3

## Background

[Provide context and motivation]

## Scope

**In Scope:**
- Item 1
- Item 2

**Out of Scope:**
- Item 1
- Item 2

design:
## Architecture

[Describe the overall architecture and approach]

## Components

- Component 1: [description]
- Component 2: [description]

## Dependencies

[List external dependencies or constraints]

acceptance_criteria:
- [ ] All child issues are completed
- [ ] Integration tests pass
- [ ] Documentation is updated
- [ ] Code review completed

issue_type: bug


title: Multi-repo hydration layer

description: Build core infrastructure to hydrate database from N repos (N≥1), with smart caching via file mtime tracking and routing writes to correct JSONL based on source_repo metadata.

design:
Components:
- Config schema for repos.additional
- source_repo metadata field (which repo owns each issue)
- Hydration logic (read from N JSONLs)
- Write routing (write to correct JSONL)
- Smart caching (file mtime tracking to avoid re-parsing)
- SQLite DB as cache layer

acceptance_criteria:
1. Can configure N repos via config.toml
2. Database hydrates from all configured repos
3. Writes route to correct JSONL via source_repo
4. File mtime caching prevents re-parsing unchanged JSONLs
5. Query performance <100ms even with 5-10 polling interval
6. N=1 (single repo) works unchanged

status: open

issue_type: epic

type: parent-child

created_by: daemon


title: Add label-based filtering to bd ready command

description:
Allow filtering ready work by labels to help organize work by sprint, week, or category.

Example usage:
  bd ready --label week1-2
  bd ready --label frontend,high-priority

This helps teams organize work into batches and makes it easier for agents to focus on specific categories of work.

Implementation notes:
- Add --label flag to ready command
- Support comma-separated labels (AND logic)
- Should work with existing ready work logic (unblocked issues)


title: Multi-repo contributor workflow support

description: Implement separate repository support for OSS contributors to prevent PR pollution while maintaining git ledger and multi-clone sync. Based on contributor-workflow-analysis.md Solution #4.

design:
See docs/contributor-workflow-analysis.md for complete design rationale.

Key architecture:
- N ≥ 1 repos (single repo default, multi-repo opt-in)
- VCS-agnostic (git, jj, hg, sapling)
- Config-based routing (no schema changes)
- Smart caching (file mtime tracking, SQLite cache)
- Global namespace (hash-based IDs)
- Cross-repo dependencies supported

acceptance_criteria:
1. Zero PR pollution - contributor planning never reaches upstream
2. Git ledger preserved - all repos VCS-tracked
3. Backward compatible - existing single-repo workflows unchanged
4. Sub-second query performance with polling
5. Library API stable - transparent to downstream consumers like VC


title: Clarify JSONL size bounds with multi-repo

description:
The contributor-workflow-analysis.md states (line 226): 'Keep beads.jsonl small enough for agents to read (<25k)'

With multi-repo hydration, it's unclear whether this bound applies to:
- Each individual JSONL file (likely intention)
- The total hydrated size across all repos (unclear)
- Both (most conservative)

Clarification needed because:
- VC monitors .beads/issues.jsonl size to stay under limit
- With multi-repo, VC needs to know if each additional repo also has 25k limit
- Agents reading hydrated data need to know total size bounds
- Performance characteristics depend on total vs per-repo limits

Example scenario:
- Primary repo: 20k JSONL
- Planning repo: 15k JSONL
- Total hydrated: 35k
Is this acceptable or does it violate the <25k principle?

acceptance_criteria:
- Documentation explicitly states size bound applies per-repo or total
- Rationale explained (why that bound matters)
- Guidance for monitoring size with multi-repo
- If total bound exists, formula provided (e.g., sum of all repos <25k)


title: VCS-agnostic sync support

description: Make bd sync work with multiple VCS types (git, jujutsu, mercurial, sapling) by detecting VCS per repo and using appropriate sync commands, supporting mixed-VCS multi-repo configs.

design:
Features:
- Detect VCS type per repo (.git, .jj, .hg, .sl)
- Sync adapters for each VCS type
- bd sync runs appropriate commands per repo
- Handle mixed-VCS configs (git + jj + hg)
- Fallback to manual sync if no VCS detected

Example:
bd sync auto-detects:
- . is git → git pull
- ~/.beads-planning is jj → jj git fetch && jj rebase
- ~/other is hg → hg pull && hg update

acceptance_criteria:
1. Detect VCS type per configured repo
2. bd sync works with git, jj, hg, sapling
3. Mixed-VCS configs supported
4. Graceful fallback if no VCS detected
5. Error messages guide user on manual sync
6. Pure git workflows unchanged


title: Add migration guide for library consumers

description:
The contributor-workflow-analysis.md has excellent migration examples for CLI users (lines 508-549) but lacks examples for library consumers like VC that use beadsLib in Go/TypeScript code.

Library consumers need to know:
- Whether their existing code continues to work unchanged (backward compatibility)
- How config.toml is automatically read (transparent hydration)
- When and how to use explicit multi-repo configuration
- What happens if config.toml doesn't exist (defaults)

Example needed:
```go
// Before (v0.17.3)
store, err := beadsLib.NewSQLiteStorage(".beads/vc.db")

// After (v0.18.0 with multi-repo) - still works!
store, err := beadsLib.NewSQLiteStorage(".beads/vc.db")
// Automatically reads .beads/config.toml if present

// Explicit multi-repo (if needed)
cfg := beadsLib.Config{
    Primary: ".beads/vc.db",
    Additional: []string{"~/.beads-planning"},
}
store, err := beadsLib.NewStorageWithConfig(cfg)
```

acceptance_criteria:
- Section added to contributor-workflow-analysis.md for library consumers
- Code examples showing backward compatibility
- Code examples showing explicit multi-repo configuration
- Guidance on when library consumers should use multi-repo vs single-repo


title: Auto-routing and maintainer detection

description: Implement intelligent routing to automatically send new issues to correct repo based on user's maintainer vs contributor status, with discovered issues inheriting parent's source_repo.

design:
Features:
- Detect maintainer vs contributor (git config, permissions)
- Config-based routing rules (no schema changes)
- Auto-route 'bd add' to primary or planning repo
- Discovered issues inherit parent's source_repo
- Explicit override via --repo flag

Config schema:
[routing]
mode = "auto"  # auto | explicit
default = "~/.beads-planning"
[routing.auto]
maintainer = "."
contributor = "~/.beads-planning"

acceptance_criteria:
1. Auto-detect maintainer vs contributor status
2. Route bd add to correct repo automatically
3. Discovered issues inherit parent's source_repo
4. --repo flag overrides auto-routing
5. Config allows explicit routing rules
6. Works without breaking single-repo workflows


title: Migration and onboarding for multi-repo

description: Create migration tools, wizards, and documentation to help users adopt multi-repo workflow, with special focus on OSS contributor onboarding and team adoption scenarios.

design:
Components:
- Migration guide documentation
- bd migrate command to move issues between repos
- bd init --contributor wizard for OSS setup
- bd init --team wizard for team setup
- Auto-detect scenarios and prompt users
- Examples for common workflows (OSS, multi-phase, personas)

Scenarios:
1. OSS contributor (fork workflow)
2. Team member (branch workflow)
3. Multi-phase development
4. Multiple personas (architect/implementer)

acceptance_criteria:
1. Migration guide covers all scenarios
2. bd migrate moves issues with filtering
3. Init wizards guide common setups
4. Examples demonstrate key workflows
5. Auto-detection prompts users when appropriate
6. Docs updated with multi-repo patterns
7. Backward compatibility clearly documented


title: Add mermaid output format for bd dep tree

description:
Add visual dependency graph output using Mermaid format for better visualization of issue relationships.

Example usage:
  bd dep tree --format mermaid <issue-id>
  bd dep tree --format mermaid bd-42 > graph.md

This would output Mermaid syntax that can be rendered in GitHub, documentation sites, or Mermaid live editor.

Implementation notes:
- Add --format flag to dep tree command
- Support 'text' (default) and 'mermaid' formats
- Mermaid graph should show issue IDs, titles, and dependency types
- Consider using flowchart LR or graph TD syntax


title: Proposal workflow (propose/withdraw/accept)

description: Implement commands and state machine for moving issues between personal planning repos and canonical upstream repos, enabling contributors to propose work without polluting PRs.

design:
Commands:
- bd propose <id> [--target <repo>] - Move issue to target repo
- bd withdraw <id> - Un-propose (move back)
- bd accept <id> - Maintainer accepts proposal

Visibility states:
- local: Personal planning only
- proposed: Staged for upstream PR
- canonical: Accepted by upstream (default for existing)

Optional visibility field (backward compatible, defaults to canonical)

acceptance_criteria:
1. bd propose moves issue from planning to primary repo
2. bd withdraw reverses proposal
3. bd accept (maintainer) finalizes acceptance
4. Visibility field tracks state (local/proposed/canonical)
5. Backward compatible - existing issues default to canonical
6. State transitions are atomic and git-tracked


title: Clarify exclusive lock protocol compatibility with multi-repo

description:
The contributor-workflow-analysis.md proposes per-repo file locking (Decision #7) using flock on JSONL files. However, VC (a downstream library consumer) uses an exclusive lock protocol (vc-195, requires Beads v0.17.3+) that allows bd daemon and VC executor to coexist.

Need to clarify:
- Does the proposed per-repo file locking work with VC's existing exclusive lock protocol?
- Do library consumers like VC need to adapt their locking logic?
- Can multiple repos be locked atomically for cross-repo operations?

Context: contributor-workflow-analysis.md lines 662-681

acceptance_criteria:
- Documentation explicitly states compatibility or incompatibility with existing lock protocols
- If incompatible, migration path is documented for library consumers
- If compatible, example showing coexistence is provided


title: Add performance benchmarks for multi-repo hydration

description:
The contributor-workflow-analysis.md asserts sub-second queries (line 702) and describes smart caching via file mtime tracking (Decision #4, lines 584-618), but doesn't provide concrete performance benchmarks.

VC's requirement (from VC feedback section):
- Executor polls GetReadyWork() every 5-10 seconds
- Queries must be sub-second (ideally <100ms)
- Smart caching must avoid re-parsing JSONLs on every query

Suggested performance targets to validate:
- File stat overhead: <1ms per repo
- Hydration (when needed): <500ms for typical JSONL (<25k)
- Query (from cache): <10ms
- Total GetReadyWork(): <100ms (VC's requirement)

Also test at scale:
- N=1 repo (baseline)
- N=3 repos (typical)
- N=10 repos (edge case)

These benchmarks are critical for library consumers like VC that run automated polling loops.

acceptance_criteria:
- Performance benchmark suite created for multi-repo hydration
- Benchmarks cover file stat, hydration, and query times
- Tests at N=1, N=3, N=10 repo scales
- Results documented in contributor-workflow-analysis.md
- Performance targets met or issues filed for optimization


title: Add guidance for self-hosting projects

description:
The contributor-workflow-analysis.md is optimized for OSS contributors making PRs to upstream projects. However, it doesn't address projects like VC that use beads for their own development (self-hosting).

Self-hosting projects differ from OSS contributors:
- No upstream/downstream distinction (they ARE the project)
- May run automated executors (not just humans)
- In bootstrap/early phase (stability matters)
- Single team/owner (not multiple contributors with permissions)

Guidance needed on:
- When self-hosting projects should stay single-repo (default, recommended)
- When they should adopt multi-repo (team planning, multi-phase dev)
- How automated executors should handle multi-repo (if at all)
- Special considerations for projects in bootstrap phase

Examples of self-hosting projects: VC (building itself with beads), internal tools, pet projects

acceptance_criteria:
- Section added: 'For Projects Using Beads for Self-Hosting'
- Clear guidance on when to stay single-repo vs adopt multi-repo
- Recommendations for automated executor behavior with multi-repo
- Bootstrap phase considerations documented