diff --git a/claude-plugin/commands/decision.md b/claude-plugin/commands/decision.md
new file mode 100644
index 000000000..557bfb6d3
--- /dev/null
+++ b/claude-plugin/commands/decision.md
@@ -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 "
" --type decision \
+ --description "$(cat <<'EOF'
+## Decision
+
+
+
+## Rationale
+
+
+
+## Alternatives Considered
+
+- ****:
+- ****:
+
+## Affects
+
+-
+EOF
+)"
+```
+
+3. If `--affects` issue IDs were provided, link them:
+```bash
+bd dep add --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
+```
+
+Include comments for discussion history:
+```bash
+bd comments
+```
+
+## 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 --type related
+ ```
+3. Add a comment on the old decision:
+ ```bash
+ bd comments add "Superseded by : "
+ ```
+4. Close the old decision:
+ ```bash
+ bd close --reason "Superseded by "
+ ```
+
+## Add Context to an Existing Decision
+
+Use comments to append discussion, implementation notes, or revisit rationale:
+```bash
+bd comments add "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`)
diff --git a/cmd/bd/count.go b/cmd/bd/count.go
index 597506fde..20cb156a5 100644
--- a/cmd/bd/count.go
+++ b/cmd/bd/count.go
@@ -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)")
diff --git a/cmd/bd/create.go b/cmd/bd/create.go
index cb3a71114..ca9a81544 100644
--- a/cmd/bd/create.go
+++ b/cmd/bd/create.go
@@ -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)")
diff --git a/cmd/bd/create_form_test.go b/cmd/bd/create_form_test.go
index b6666e134..3a0195dc4 100644
--- a/cmd/bd/create_form_test.go
+++ b/cmd/bd/create_form_test.go
@@ -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 {
diff --git a/cmd/bd/doctor/multirepo.go b/cmd/bd/doctor/multirepo.go
index 6b54905a2..64bb5ee09 100644
--- a/cmd/bd/doctor/multirepo.go
+++ b/cmd/bd/doctor/multirepo.go
@@ -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
diff --git a/cmd/bd/list.go b/cmd/bd/list.go
index af55dc1fc..093d7293e 100644
--- a/cmd/bd/list.go
+++ b/cmd/bd/list.go
@@ -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)")
diff --git a/cmd/bd/migrate_issues.go b/cmd/bd/migrate_issues.go
index ce183311c..976a50084 100644
--- a/cmd/bd/migrate_issues.go
+++ b/cmd/bd/migrate_issues.go
@@ -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)")
diff --git a/cmd/bd/query.go b/cmd/bd/query.go
index 31b5e19fc..99e1184ab 100644
--- a/cmd/bd/query.go
+++ b/cmd/bd/query.go
@@ -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)
diff --git a/cmd/bd/search.go b/cmd/bd/search.go
index c9d83daa1..e7d8e67a4 100644
--- a/cmd/bd/search.go
+++ b/cmd/bd/search.go
@@ -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)")
diff --git a/cmd/bd/update.go b/cmd/bd/update.go
index c7687737a..48851190e 100644
--- a/cmd/bd/update.go
+++ b/cmd/bd/update.go
@@ -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")
diff --git a/integrations/beads-mcp/README.md b/integrations/beads-mcp/README.md
index 3fde03829..56eadeb5e 100644
--- a/integrations/beads-mcp/README.md
+++ b/integrations/beads-mcp/README.md
@@ -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
diff --git a/integrations/beads-mcp/src/beads_mcp/models.py b/integrations/beads-mcp/src/beads_mcp/models.py
index b2682ec60..3a646ed4c 100644
--- a/integrations/beads-mcp/src/beads_mcp/models.py
+++ b/integrations/beads-mcp/src/beads_mcp/models.py
@@ -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"]
diff --git a/integrations/beads-mcp/src/beads_mcp/server.py b/integrations/beads-mcp/src/beads_mcp/server.py
index a18530706..a7a5817b6 100644
--- a/integrations/beads-mcp/src/beads_mcp/server.py
+++ b/integrations/beads-mcp/src/beads_mcp/server.py
@@ -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
diff --git a/integrations/beads-mcp/src/beads_mcp/tools.py b/integrations/beads-mcp/src/beads_mcp/tools.py
index fef5df010..ec6c1cf9b 100644
--- a/integrations/beads-mcp/src/beads_mcp/tools.py
+++ b/integrations/beads-mcp/src/beads_mcp/tools.py
@@ -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,
diff --git a/internal/types/types.go b/internal/types/types.go
index 7984209de..8e77c6486 100644
--- a/internal/types/types.go
+++ b/internal/types/types.go
@@ -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
diff --git a/internal/types/types_test.go b/internal/types/types_test.go
index 04e1e2983..f711581c7 100644
--- a/internal/types/types_test.go
+++ b/internal/types/types_test.go
@@ -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, ""},