feat: add decision as built-in issue type
Projects track what they're doing (issues) and what happened (events), but not why they chose a particular approach. Decisions are a missing first-class concept -- every project has them, they're distinct from tasks, and they're the context hardest to recover after the fact. Adds TypeDecision as a core work type alongside bug/feature/task/epic/chore. Includes aliases (dec, adr), required sections template (Decision, Rationale, Alternatives Considered), and a Claude plugin command for structured recording. Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com> Executed-By: beads/crew/emma Rig: beads Role: crew
This commit is contained in:
parent
7d5ee8b97a
commit
aba0cab3cd
16 changed files with 156 additions and 25 deletions
111
claude-plugin/commands/decision.md
Normal file
111
claude-plugin/commands/decision.md
Normal file
|
|
@ -0,0 +1,111 @@
|
|||
---
|
||||
description: Record, list, and manage project decisions with rationale tracking
|
||||
argument-hint: record|list|show|supersede
|
||||
---
|
||||
|
||||
Record and track project decisions as beads issues with structured rationale, alternatives considered, and links to affected work.
|
||||
|
||||
Decisions use `--type decision`. The description field holds the structured decision record.
|
||||
|
||||
## Record a Decision
|
||||
|
||||
When the user wants to record a decision (or you invoke `bd decision record`):
|
||||
|
||||
1. Gather the following (ask if not provided):
|
||||
- **Title**: Short summary of what was decided (required)
|
||||
- **Rationale**: Why this was chosen (required)
|
||||
- **Alternatives**: What else was considered (optional but encouraged)
|
||||
- **Affects**: Issue IDs this decision impacts (optional)
|
||||
- **Priority**: How important (default P2)
|
||||
|
||||
2. Create the issue with structured description:
|
||||
|
||||
```bash
|
||||
bd create "<title>" --type decision \
|
||||
--description "$(cat <<'EOF'
|
||||
## Decision
|
||||
|
||||
<one-sentence summary of what was decided>
|
||||
|
||||
## Rationale
|
||||
|
||||
<why this was chosen>
|
||||
|
||||
## Alternatives Considered
|
||||
|
||||
- **<alt 1>**: <why rejected>
|
||||
- **<alt 2>**: <why rejected>
|
||||
|
||||
## Affects
|
||||
|
||||
- <issue IDs or area descriptions>
|
||||
EOF
|
||||
)"
|
||||
```
|
||||
|
||||
3. If `--affects` issue IDs were provided, link them:
|
||||
```bash
|
||||
bd dep add <decision-id> <affected-id> --type related
|
||||
```
|
||||
|
||||
4. Show the created decision to the user.
|
||||
|
||||
## List Decisions
|
||||
|
||||
```bash
|
||||
bd list --type decision
|
||||
```
|
||||
|
||||
To see all decisions including closed/superseded:
|
||||
```bash
|
||||
bd list --type decision --all
|
||||
```
|
||||
|
||||
## Show a Decision
|
||||
|
||||
```bash
|
||||
bd show <decision-id>
|
||||
```
|
||||
|
||||
Include comments for discussion history:
|
||||
```bash
|
||||
bd comments <decision-id>
|
||||
```
|
||||
|
||||
## Supersede a Decision
|
||||
|
||||
When a decision is replaced by a new one:
|
||||
|
||||
1. Record the new decision (as above)
|
||||
2. Link the new decision to the old one:
|
||||
```bash
|
||||
bd dep add <new-id> <old-id> --type related
|
||||
```
|
||||
3. Add a comment on the old decision:
|
||||
```bash
|
||||
bd comments add <old-id> "Superseded by <new-id>: <brief reason>"
|
||||
```
|
||||
4. Close the old decision:
|
||||
```bash
|
||||
bd close <old-id> --reason "Superseded by <new-id>"
|
||||
```
|
||||
|
||||
## Add Context to an Existing Decision
|
||||
|
||||
Use comments to append discussion, implementation notes, or revisit rationale:
|
||||
```bash
|
||||
bd comments add <decision-id> "Implementation note: ..."
|
||||
```
|
||||
|
||||
## Search Decisions
|
||||
|
||||
```bash
|
||||
bd search "keyword" --type decision
|
||||
```
|
||||
|
||||
## Conventions
|
||||
|
||||
- **Status**: `open` = active decision, `closed` = superseded or reversed
|
||||
- **Description format**: Use the structured template above for consistency
|
||||
- **Linking**: Use `related` dependency type to connect decisions to affected issues
|
||||
- **Labels**: Use labels for categorizing decisions (e.g., `architecture`, `tooling`, `process`)
|
||||
|
|
@ -311,7 +311,7 @@ func init() {
|
|||
countCmd.Flags().StringP("status", "s", "", "Filter by status (open, in_progress, blocked, deferred, closed)")
|
||||
countCmd.Flags().IntP("priority", "p", 0, "Filter by priority (0-4: 0=critical, 1=high, 2=medium, 3=low, 4=backlog)")
|
||||
countCmd.Flags().StringP("assignee", "a", "", "Filter by assignee")
|
||||
countCmd.Flags().StringP("type", "t", "", "Filter by type (bug, feature, task, epic, chore, merge-request, molecule, gate)")
|
||||
countCmd.Flags().StringP("type", "t", "", "Filter by type (bug, feature, task, epic, chore, decision, merge-request, molecule, gate)")
|
||||
countCmd.Flags().StringSliceP("label", "l", []string{}, "Filter by labels (AND: must have ALL)")
|
||||
countCmd.Flags().StringSlice("label-any", []string{}, "Filter by labels (OR: must have AT LEAST ONE)")
|
||||
countCmd.Flags().String("title", "", "Filter by title text (case-insensitive substring match)")
|
||||
|
|
|
|||
|
|
@ -776,7 +776,7 @@ func init() {
|
|||
createCmd.Flags().Bool("silent", false, "Output only the issue ID (for scripting)")
|
||||
createCmd.Flags().Bool("dry-run", false, "Preview what would be created without actually creating")
|
||||
registerPriorityFlag(createCmd, "2")
|
||||
createCmd.Flags().StringP("type", "t", "task", "Issue type (bug|feature|task|epic|chore|merge-request|molecule|gate|agent|role|rig|convoy|event); enhancement is alias for feature")
|
||||
createCmd.Flags().StringP("type", "t", "task", "Issue type (bug|feature|task|epic|chore|decision|merge-request|molecule|gate|agent|role|rig|convoy|event); aliases: enhancement/feat→feature, dec/adr→decision")
|
||||
registerCommonIssueFlags(createCmd)
|
||||
createCmd.Flags().String("spec-id", "", "Link to specification document")
|
||||
createCmd.Flags().StringSliceP("labels", "l", []string{}, "Labels (comma-separated)")
|
||||
|
|
|
|||
|
|
@ -393,13 +393,14 @@ func TestCreateIssueFromFormValues(t *testing.T) {
|
|||
})
|
||||
|
||||
t.Run("AllIssueTypes", func(t *testing.T) {
|
||||
issueTypes := []string{"bug", "feature", "task", "epic", "chore"}
|
||||
issueTypes := []string{"bug", "feature", "task", "epic", "chore", "decision"}
|
||||
expectedTypes := []types.IssueType{
|
||||
types.TypeBug,
|
||||
types.TypeFeature,
|
||||
types.TypeTask,
|
||||
types.TypeEpic,
|
||||
types.TypeChore,
|
||||
types.TypeDecision,
|
||||
}
|
||||
|
||||
for i, issueType := range issueTypes {
|
||||
|
|
|
|||
|
|
@ -212,7 +212,7 @@ func findUnknownTypesInHydratedIssues(repoPath string, multiRepo *config.MultiRe
|
|||
// Collect all known types (core work types + parent custom + all child custom)
|
||||
// Only core work types are built-in; Gas Town types require types.custom config.
|
||||
knownTypes := map[string]bool{
|
||||
"bug": true, "feature": true, "task": true, "epic": true, "chore": true,
|
||||
"bug": true, "feature": true, "task": true, "epic": true, "chore": true, "decision": true,
|
||||
}
|
||||
|
||||
// Add parent's custom types
|
||||
|
|
|
|||
|
|
@ -787,7 +787,7 @@ func init() {
|
|||
listCmd.Flags().StringP("status", "s", "", "Filter by status (open, in_progress, blocked, deferred, closed)")
|
||||
registerPriorityFlag(listCmd, "")
|
||||
listCmd.Flags().StringP("assignee", "a", "", "Filter by assignee")
|
||||
listCmd.Flags().StringP("type", "t", "", "Filter by type (bug, feature, task, epic, chore, merge-request, molecule, gate, convoy). Aliases: mr→merge-request, feat→feature, mol→molecule")
|
||||
listCmd.Flags().StringP("type", "t", "", "Filter by type (bug, feature, task, epic, chore, decision, merge-request, molecule, gate, convoy). Aliases: mr→merge-request, feat→feature, mol→molecule, dec/adr→decision")
|
||||
listCmd.Flags().StringSliceP("label", "l", []string{}, "Filter by labels (AND: must have ALL). Can combine with --label-any")
|
||||
listCmd.Flags().StringSlice("label-any", []string{}, "Filter by labels (OR: must have AT LEAST ONE). Can combine with --label")
|
||||
listCmd.Flags().String("label-pattern", "", "Filter by label glob pattern (e.g., 'tech-*' matches tech-debt, tech-legacy)")
|
||||
|
|
|
|||
|
|
@ -656,7 +656,7 @@ func init() {
|
|||
migrateIssuesCmd.Flags().String("to", "", "Destination repository (required)")
|
||||
migrateIssuesCmd.Flags().String("status", "", "Filter by status (open/closed/all)")
|
||||
migrateIssuesCmd.Flags().Int("priority", -1, "Filter by priority (0-4)")
|
||||
migrateIssuesCmd.Flags().String("type", "", "Filter by issue type (bug/feature/task/epic/chore)")
|
||||
migrateIssuesCmd.Flags().String("type", "", "Filter by issue type (bug/feature/task/epic/chore/decision)")
|
||||
migrateIssuesCmd.Flags().StringSlice("label", nil, "Filter by labels (can specify multiple)")
|
||||
migrateIssuesCmd.Flags().StringSlice("id", nil, "Specific issue IDs to migrate (can specify multiple)")
|
||||
migrateIssuesCmd.Flags().String("ids-file", "", "File containing issue IDs (one per line)")
|
||||
|
|
|
|||
|
|
@ -39,7 +39,7 @@ Boolean operators (case-insensitive):
|
|||
Supported fields:
|
||||
status Issue status (open, in_progress, blocked, deferred, closed)
|
||||
priority Priority level (0-4)
|
||||
type Issue type (bug, feature, task, epic, chore)
|
||||
type Issue type (bug, feature, task, epic, chore, decision)
|
||||
assignee Assigned user (use "none" for unassigned)
|
||||
owner Issue owner
|
||||
label Issue label (use "none" for unlabeled)
|
||||
|
|
|
|||
|
|
@ -329,7 +329,7 @@ func init() {
|
|||
searchCmd.Flags().String("query", "", "Search query (alternative to positional argument)")
|
||||
searchCmd.Flags().StringP("status", "s", "", "Filter by status (open, in_progress, blocked, deferred, closed)")
|
||||
searchCmd.Flags().StringP("assignee", "a", "", "Filter by assignee")
|
||||
searchCmd.Flags().StringP("type", "t", "", "Filter by type (bug, feature, task, epic, chore, merge-request, molecule, gate)")
|
||||
searchCmd.Flags().StringP("type", "t", "", "Filter by type (bug, feature, task, epic, chore, decision, merge-request, molecule, gate)")
|
||||
searchCmd.Flags().StringSliceP("label", "l", []string{}, "Filter by labels (AND: must have ALL)")
|
||||
searchCmd.Flags().StringSlice("label-any", []string{}, "Filter by labels (OR: must have AT LEAST ONE)")
|
||||
searchCmd.Flags().IntP("limit", "n", 50, "Limit results (default: 50)")
|
||||
|
|
|
|||
|
|
@ -136,7 +136,7 @@ create, update, show, or close operation).`,
|
|||
customTypes = config.GetCustomTypesFromYAML()
|
||||
}
|
||||
if !types.IssueType(issueType).IsValidWithCustom(customTypes) {
|
||||
validTypes := "bug, feature, task, epic, chore"
|
||||
validTypes := "bug, feature, task, epic, chore, decision"
|
||||
if len(customTypes) > 0 {
|
||||
validTypes += ", " + joinStrings(customTypes, ", ")
|
||||
}
|
||||
|
|
@ -408,7 +408,7 @@ func init() {
|
|||
updateCmd.Flags().StringP("status", "s", "", "New status")
|
||||
registerPriorityFlag(updateCmd, "")
|
||||
updateCmd.Flags().String("title", "", "New title")
|
||||
updateCmd.Flags().StringP("type", "t", "", "New type (bug|feature|task|epic|chore|merge-request|molecule|gate|agent|role|rig|convoy|event|slot)")
|
||||
updateCmd.Flags().StringP("type", "t", "", "New type (bug|feature|task|epic|chore|decision|merge-request|molecule|gate|agent|role|rig|convoy|event|slot)")
|
||||
registerCommonIssueFlags(updateCmd)
|
||||
updateCmd.Flags().String("spec-id", "", "Link to specification document")
|
||||
updateCmd.Flags().String("acceptance-criteria", "", "DEPRECATED: use --acceptance")
|
||||
|
|
|
|||
|
|
@ -214,7 +214,7 @@ await beads_ready_work(workspace_root="/Users/you/project-a")
|
|||
|
||||
**Tools (all support `workspace_root` parameter):**
|
||||
- `init` - Initialize bd in current directory
|
||||
- `create` - Create new issue (bug, feature, task, epic, chore)
|
||||
- `create` - Create new issue (bug, feature, task, epic, chore, decision)
|
||||
- `list` - List issues with filters (status, priority, type, assignee)
|
||||
- `ready` - Find tasks with no blockers ready to work on
|
||||
- `show` - Show detailed issue info including dependencies
|
||||
|
|
|
|||
|
|
@ -14,7 +14,7 @@ from pydantic import BaseModel, Field, field_validator
|
|||
#
|
||||
# The CLI handles validation of these values against the configured options.
|
||||
# Built-in statuses: open, in_progress, blocked, deferred, closed
|
||||
# Built-in types: bug, feature, task, epic, chore
|
||||
# Built-in types: bug, feature, task, epic, chore, decision
|
||||
IssueStatus = str
|
||||
IssueType = str
|
||||
DependencyType = Literal["blocks", "related", "parent-child", "discovered-from"]
|
||||
|
|
|
|||
|
|
@ -385,7 +385,7 @@ async def get_tool_info(tool_name: str) -> dict[str, Any]:
|
|||
"parameters": {
|
||||
"status": "open|in_progress|blocked|deferred|closed or custom (optional)",
|
||||
"priority": "int 0-4 (optional)",
|
||||
"issue_type": "bug|feature|task|epic|chore or custom (optional)",
|
||||
"issue_type": "bug|feature|task|epic|chore|decision or custom (optional)",
|
||||
"assignee": "str (optional)",
|
||||
"labels": "list[str] (optional) - AND filter: must have ALL labels",
|
||||
"labels_any": "list[str] (optional) - OR filter: must have at least one",
|
||||
|
|
@ -421,7 +421,7 @@ async def get_tool_info(tool_name: str) -> dict[str, Any]:
|
|||
"title": "str (required)",
|
||||
"description": "str (default '')",
|
||||
"priority": "int 0-4 (default 2)",
|
||||
"issue_type": "bug|feature|task|epic|chore or custom (default task)",
|
||||
"issue_type": "bug|feature|task|epic|chore|decision or custom (default task)",
|
||||
"assignee": "str (optional)",
|
||||
"labels": "list[str] (optional)",
|
||||
"deps": "list[str] (optional) - dependency IDs",
|
||||
|
|
@ -862,7 +862,7 @@ async def list_issues(
|
|||
Args:
|
||||
status: Filter by status (open, in_progress, blocked, closed)
|
||||
priority: Filter by priority level (0-4)
|
||||
issue_type: Filter by type (bug, feature, task, epic, chore)
|
||||
issue_type: Filter by type (bug, feature, task, epic, chore, decision)
|
||||
assignee: Filter by assignee
|
||||
labels: Filter by labels (AND: must have ALL specified labels)
|
||||
labels_any: Filter by labels (OR: must have at least one)
|
||||
|
|
@ -964,7 +964,7 @@ async def show_issue(
|
|||
|
||||
@mcp.tool(
|
||||
name="create",
|
||||
description="""Create a new issue (bug, feature, task, epic, or chore) with optional design,
|
||||
description="""Create a new issue (bug, feature, task, epic, chore, or decision) with optional design,
|
||||
acceptance criteria, and dependencies.""",
|
||||
)
|
||||
@with_workspace
|
||||
|
|
|
|||
|
|
@ -394,7 +394,7 @@ async def beads_ready_work(
|
|||
async def beads_list_issues(
|
||||
status: Annotated[IssueStatus | None, "Filter by status (open, in_progress, blocked, deferred, closed, or custom)"] = None,
|
||||
priority: Annotated[int | None, "Filter by priority (0-4, 0=highest)"] = None,
|
||||
issue_type: Annotated[IssueType | None, "Filter by type (bug, feature, task, epic, chore, or custom)"] = None,
|
||||
issue_type: Annotated[IssueType | None, "Filter by type (bug, feature, task, epic, chore, decision, or custom)"] = None,
|
||||
assignee: Annotated[str | None, "Filter by assignee"] = None,
|
||||
labels: Annotated[list[str] | None, "Filter by labels (AND: must have ALL)"] = None,
|
||||
labels_any: Annotated[list[str] | None, "Filter by labels (OR: must have at least one)"] = None,
|
||||
|
|
@ -438,7 +438,7 @@ async def beads_create_issue(
|
|||
acceptance: Annotated[str | None, "Acceptance criteria"] = None,
|
||||
external_ref: Annotated[str | None, "External reference (e.g., gh-9, jira-ABC)"] = None,
|
||||
priority: Annotated[int, "Priority (0-4, 0=highest)"] = 2,
|
||||
issue_type: Annotated[IssueType, "Type: bug, feature, task, epic, chore, or custom"] = DEFAULT_ISSUE_TYPE,
|
||||
issue_type: Annotated[IssueType, "Type: bug, feature, task, epic, chore, decision, or custom"] = DEFAULT_ISSUE_TYPE,
|
||||
assignee: Annotated[str | None, "Assignee username"] = None,
|
||||
labels: Annotated[list[str] | None, "List of labels"] = None,
|
||||
id: Annotated[str | None, "Explicit issue ID (e.g., bd-42)"] = None,
|
||||
|
|
|
|||
|
|
@ -501,11 +501,12 @@ type IssueType string
|
|||
// Core work type constants - these are the built-in types that beads validates.
|
||||
// All other types require configuration via types.custom in config.yaml.
|
||||
const (
|
||||
TypeBug IssueType = "bug"
|
||||
TypeFeature IssueType = "feature"
|
||||
TypeTask IssueType = "task"
|
||||
TypeEpic IssueType = "epic"
|
||||
TypeChore IssueType = "chore"
|
||||
TypeBug IssueType = "bug"
|
||||
TypeFeature IssueType = "feature"
|
||||
TypeTask IssueType = "task"
|
||||
TypeEpic IssueType = "epic"
|
||||
TypeChore IssueType = "chore"
|
||||
TypeDecision IssueType = "decision"
|
||||
)
|
||||
|
||||
// TypeEvent is a system-internal type used by set-state for audit trail beads.
|
||||
|
|
@ -520,11 +521,11 @@ const TypeEvent IssueType = "event"
|
|||
// (event was also a Gas Town type but was promoted to a built-in internal type above.)
|
||||
|
||||
// IsValid checks if the issue type is a core work type.
|
||||
// Only core work types (bug, feature, task, epic, chore) are built-in.
|
||||
// Only core work types (bug, feature, task, epic, chore, decision) are built-in.
|
||||
// Other types (molecule, gate, convoy, etc.) require types.custom configuration.
|
||||
func (t IssueType) IsValid() bool {
|
||||
switch t {
|
||||
case TypeBug, TypeFeature, TypeTask, TypeEpic, TypeChore:
|
||||
case TypeBug, TypeFeature, TypeTask, TypeEpic, TypeChore, TypeDecision:
|
||||
return true
|
||||
}
|
||||
return false
|
||||
|
|
@ -560,6 +561,8 @@ func (t IssueType) Normalize() IssueType {
|
|||
switch strings.ToLower(string(t)) {
|
||||
case "enhancement", "feat":
|
||||
return TypeFeature
|
||||
case "dec", "adr":
|
||||
return TypeDecision
|
||||
default:
|
||||
return t
|
||||
}
|
||||
|
|
@ -589,6 +592,12 @@ func (t IssueType) RequiredSections() []RequiredSection {
|
|||
return []RequiredSection{
|
||||
{Heading: "## Success Criteria", Hint: "Define high-level success criteria"},
|
||||
}
|
||||
case TypeDecision:
|
||||
return []RequiredSection{
|
||||
{Heading: "## Decision", Hint: "Summarize what was decided"},
|
||||
{Heading: "## Rationale", Hint: "Explain why this option was chosen"},
|
||||
{Heading: "## Alternatives Considered", Hint: "List alternatives and why they were rejected"},
|
||||
}
|
||||
default:
|
||||
// Chore and custom types have no required sections
|
||||
return nil
|
||||
|
|
|
|||
|
|
@ -545,6 +545,7 @@ func TestIssueTypeIsValid(t *testing.T) {
|
|||
{TypeTask, true},
|
||||
{TypeEpic, true},
|
||||
{TypeChore, true},
|
||||
{TypeDecision, true},
|
||||
// Gas Town types are now custom types (not built-in)
|
||||
{IssueType("message"), false},
|
||||
{IssueType("merge-request"), false},
|
||||
|
|
@ -621,6 +622,14 @@ func TestEventTypeValidation(t *testing.T) {
|
|||
if TypeEvent.Normalize() != TypeEvent {
|
||||
t.Errorf("TypeEvent.Normalize() = %q, want %q", TypeEvent.Normalize(), TypeEvent)
|
||||
}
|
||||
|
||||
// decision aliases
|
||||
if IssueType("dec").Normalize() != TypeDecision {
|
||||
t.Errorf("IssueType(dec).Normalize() = %q, want %q", IssueType("dec").Normalize(), TypeDecision)
|
||||
}
|
||||
if IssueType("adr").Normalize() != TypeDecision {
|
||||
t.Errorf("IssueType(adr).Normalize() = %q, want %q", IssueType("adr").Normalize(), TypeDecision)
|
||||
}
|
||||
}
|
||||
|
||||
func TestIssueTypeRequiredSections(t *testing.T) {
|
||||
|
|
@ -633,6 +642,7 @@ func TestIssueTypeRequiredSections(t *testing.T) {
|
|||
{TypeFeature, 1, "## Acceptance Criteria"},
|
||||
{TypeTask, 1, "## Acceptance Criteria"},
|
||||
{TypeEpic, 1, "## Success Criteria"},
|
||||
{TypeDecision, 3, "## Decision"},
|
||||
{TypeChore, 0, ""},
|
||||
// Gas Town types are now custom and have no required sections
|
||||
{IssueType("message"), 0, ""},
|
||||
|
|
|
|||
Loading…
Add table
Add a link
Reference in a new issue