f03c754df1
Move all plugin content to claude-plugin/ subdirectory for cleaner separation from core beads functionality: - claude-plugin/.claude-plugin/plugin.json - plugin manifest - claude-plugin/commands/ - all slash commands - claude-plugin/agents/ - task-agent (now in correct location) - claude-plugin/skills/beads/ - beads skill with resources Root .claude-plugin/ now only contains marketplace.json pointing to ./claude-plugin. Note: After updating, users may need to clear plugin cache: rm -rf ~/.claude/plugins/cache/beads-marketplace/ Fixes #985 Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com> Executed-By: beads/crew/dave Rig: beads Role: crew
338 lines
6.5 KiB
Markdown
338 lines
6.5 KiB
Markdown
# bd template
|
|
|
|
Manage issue templates for streamlined issue creation.
|
|
|
|
## Synopsis
|
|
|
|
Templates provide pre-filled structures for common issue types, making it faster to create well-formed issues with consistent formatting.
|
|
|
|
```bash
|
|
bd template list
|
|
bd template show <template-name>
|
|
bd template create <template-name>
|
|
```
|
|
|
|
## Description
|
|
|
|
Templates can be:
|
|
- **Built-in**: Provided by bd (epic, bug, feature)
|
|
- **Custom**: Stored in `.beads/templates/` directory
|
|
|
|
Each template defines default values for:
|
|
- Description structure with placeholders
|
|
- Issue type (bug, feature, task, epic, chore)
|
|
- Priority (0-4)
|
|
- Labels
|
|
- Design notes structure
|
|
- Acceptance criteria structure
|
|
|
|
## Commands
|
|
|
|
### list
|
|
|
|
List all available templates (built-in and custom).
|
|
|
|
```bash
|
|
bd template list
|
|
bd template list --json
|
|
```
|
|
|
|
**Examples:**
|
|
|
|
```bash
|
|
$ bd template list
|
|
Built-in Templates:
|
|
epic
|
|
Type: epic, Priority: P1
|
|
Labels: epic
|
|
bug
|
|
Type: bug, Priority: P1
|
|
Labels: bug
|
|
feature
|
|
Type: feature, Priority: P2
|
|
Labels: feature
|
|
```
|
|
|
|
### show
|
|
|
|
Show detailed structure of a specific template.
|
|
|
|
```bash
|
|
bd template show <template-name>
|
|
bd template show <template-name> --json
|
|
```
|
|
|
|
**Examples:**
|
|
|
|
```bash
|
|
$ bd template show bug
|
|
Template: bug
|
|
Type: bug
|
|
Priority: P1
|
|
Labels: bug
|
|
|
|
Description:
|
|
## Summary
|
|
|
|
[Brief description of the bug]
|
|
|
|
## Steps to Reproduce
|
|
...
|
|
```
|
|
|
|
### create
|
|
|
|
Create a custom template in `.beads/templates/` directory.
|
|
|
|
```bash
|
|
bd template create <template-name>
|
|
```
|
|
|
|
This creates a YAML file with default structure that you can edit to customize.
|
|
|
|
**Examples:**
|
|
|
|
```bash
|
|
$ bd template create performance
|
|
✓ Created template: .beads/templates/performance.yaml
|
|
Edit the file to customize your template.
|
|
|
|
$ cat .beads/templates/performance.yaml
|
|
name: performance
|
|
description: |-
|
|
[Describe the issue]
|
|
|
|
## Additional Context
|
|
|
|
[Add relevant details]
|
|
type: task
|
|
priority: 2
|
|
labels: []
|
|
design: '[Design notes]'
|
|
acceptance_criteria: |-
|
|
- [ ] Acceptance criterion 1
|
|
- [ ] Acceptance criterion 2
|
|
|
|
# Edit the template to customize it
|
|
$ vim .beads/templates/performance.yaml
|
|
```
|
|
|
|
## Using Templates with `bd create`
|
|
|
|
Use the `--from-template` flag to create issues from templates:
|
|
|
|
```bash
|
|
bd create --from-template <template-name> "Issue title"
|
|
```
|
|
|
|
Template values can be overridden with explicit flags:
|
|
|
|
```bash
|
|
# Use bug template but override priority
|
|
bd create --from-template bug "Login crashes on special chars" -p 0
|
|
|
|
# Use epic template but add extra labels
|
|
bd create --from-template epic "Q4 Infrastructure" -l infrastructure,ops
|
|
```
|
|
|
|
**Examples:**
|
|
|
|
```bash
|
|
# Create epic from template
|
|
$ bd create --from-template epic "Phase 3 Features"
|
|
✓ Created issue: bd-a3f8e9
|
|
Title: Phase 3 Features
|
|
Priority: P1
|
|
Status: open
|
|
|
|
# Create bug report from template
|
|
$ bd create --from-template bug "Auth token validation fails"
|
|
✓ Created issue: bd-42bc7a
|
|
Title: Auth token validation fails
|
|
Priority: P1
|
|
Status: open
|
|
|
|
# Use custom template
|
|
$ bd template create security-audit
|
|
$ bd create --from-template security-audit "Review authentication flow"
|
|
```
|
|
|
|
## Template File Format
|
|
|
|
Templates are YAML files with the following structure:
|
|
|
|
```yaml
|
|
name: template-name
|
|
description: |
|
|
Multi-line description with placeholders
|
|
|
|
## Section heading
|
|
|
|
[Placeholder text]
|
|
|
|
type: bug|feature|task|epic|chore
|
|
priority: 0-4
|
|
labels:
|
|
- label1
|
|
- label2
|
|
|
|
design: |
|
|
Design notes structure
|
|
|
|
acceptance_criteria: |
|
|
- [ ] Acceptance criterion 1
|
|
- [ ] Acceptance criterion 2
|
|
```
|
|
|
|
## Built-in Templates
|
|
|
|
### epic
|
|
|
|
For large features composed of multiple issues.
|
|
|
|
**Structure:**
|
|
- Overview and scope
|
|
- Success criteria checklist
|
|
- Background and motivation
|
|
- In-scope / out-of-scope sections
|
|
- Architecture design notes
|
|
- Component breakdown
|
|
|
|
**Defaults:**
|
|
- Type: epic
|
|
- Priority: P1
|
|
- Labels: epic
|
|
|
|
### bug
|
|
|
|
For bug reports with consistent structure.
|
|
|
|
**Structure:**
|
|
- Summary
|
|
- Steps to reproduce
|
|
- Expected vs actual behavior
|
|
- Environment details
|
|
- Root cause analysis (design)
|
|
- Proposed fix
|
|
- Impact assessment
|
|
|
|
**Defaults:**
|
|
- Type: bug
|
|
- Priority: P1
|
|
- Labels: bug
|
|
|
|
### feature
|
|
|
|
For feature requests and enhancements.
|
|
|
|
**Structure:**
|
|
- Feature description
|
|
- Motivation and use cases
|
|
- Proposed solution
|
|
- Alternatives considered
|
|
- Technical design
|
|
- API changes
|
|
- Testing strategy
|
|
|
|
**Defaults:**
|
|
- Type: feature
|
|
- Priority: P2
|
|
- Labels: feature
|
|
|
|
## Custom Templates
|
|
|
|
Custom templates override built-in templates with the same name. This allows you to customize built-in templates for your project.
|
|
|
|
**Priority:**
|
|
1. Custom templates in `.beads/templates/`
|
|
2. Built-in templates
|
|
|
|
**Example - Override bug template:**
|
|
|
|
```bash
|
|
# Create custom bug template
|
|
$ bd template create bug
|
|
|
|
# Edit to add project-specific fields
|
|
$ cat > .beads/templates/bug.yaml << 'EOF'
|
|
name: bug
|
|
description: |
|
|
## Bug Report
|
|
|
|
**Severity:** [critical|high|medium|low]
|
|
**Component:** [auth|api|frontend|backend]
|
|
|
|
## Description
|
|
[Describe the bug]
|
|
|
|
## Reproduction
|
|
1. Step 1
|
|
2. Step 2
|
|
|
|
## Impact
|
|
[Who is affected? How many users?]
|
|
|
|
type: bug
|
|
priority: 0
|
|
labels:
|
|
- bug
|
|
- needs-triage
|
|
|
|
design: |
|
|
## Investigation Notes
|
|
[Technical details]
|
|
|
|
acceptance_criteria: |
|
|
- [ ] Bug fixed and verified
|
|
- [ ] Tests added
|
|
- [ ] Monitoring added
|
|
EOF
|
|
|
|
# Now 'bd create --from-template bug' uses your custom template
|
|
```
|
|
|
|
## JSON Output
|
|
|
|
All template commands support `--json` flag for programmatic use:
|
|
|
|
```bash
|
|
$ bd template list --json
|
|
[
|
|
{
|
|
"name": "epic",
|
|
"description": "## Overview...",
|
|
"type": "epic",
|
|
"priority": 1,
|
|
"labels": ["epic"],
|
|
"design": "## Architecture...",
|
|
"acceptance_criteria": "- [ ] All child issues..."
|
|
}
|
|
]
|
|
|
|
$ bd template show bug --json
|
|
{
|
|
"name": "bug",
|
|
"description": "## Summary...",
|
|
"type": "bug",
|
|
"priority": 1,
|
|
"labels": ["bug"],
|
|
"design": "## Root Cause...",
|
|
"acceptance_criteria": "- [ ] Bug no longer..."
|
|
}
|
|
```
|
|
|
|
## Best Practices
|
|
|
|
1. **Use templates for consistency**: Establish team conventions for common issue types
|
|
2. **Customize built-ins**: Override built-in templates to match your workflow
|
|
3. **Version control templates**: Commit `.beads/templates/` to share across team
|
|
4. **Keep templates focused**: Create specific templates (e.g., `performance`, `security-audit`) rather than generic ones
|
|
5. **Use placeholders**: Mark sections requiring input with `[brackets]` or `TODO`
|
|
6. **Include checklists**: Use `- [ ]` for actionable items in description and acceptance criteria
|
|
|
|
## See Also
|
|
|
|
- [bd create](create.md) - Create issues
|
|
- [bd list](list.md) - List issues
|
|
- [README](../README.md) - Main documentation
|