Add template support for issue creation (bd-164b)
- Built-in templates: epic, bug, feature (embedded in binary) - Custom templates in .beads/templates/ (override built-ins) - Commands: bd template list/show/create - Flag: bd create --from-template <name> "Title" - Template fields: description, type, priority, labels, design, acceptance - Security: sanitize template names to prevent path traversal - Flag precedence: explicit flags override template defaults - Tests: template loading, security, flag precedence - Docs: commands/template.md and README.md updated Closes bd-164b Amp-Thread-ID: https://ampcode.com/threads/T-118fe54f-b112-4f99-a3d9-b7df53fb7284 Co-authored-by: Amp <amp@ampcode.com>
This commit is contained in:
Steve Yegge
337
commands/template.md
Normal file
337
commands/template.md
Normal file
@@ -0,0 +1,337 @@
|
||||
# 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
|
||||
Reference in New Issue
Block a user