From aba0cab3cd8bbef7b49f09e0166bc52f50f3f765 Mon Sep 17 00:00:00 2001 From: mayor Date: Thu, 12 Feb 2026 00:42:50 +0100 Subject: [PATCH] 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 Executed-By: beads/crew/emma Rig: beads Role: crew --- claude-plugin/commands/decision.md | 111 ++++++++++++++++++ cmd/bd/count.go | 2 +- cmd/bd/create.go | 2 +- cmd/bd/create_form_test.go | 3 +- cmd/bd/doctor/multirepo.go | 2 +- cmd/bd/list.go | 2 +- cmd/bd/migrate_issues.go | 2 +- cmd/bd/query.go | 2 +- cmd/bd/search.go | 2 +- cmd/bd/update.go | 4 +- integrations/beads-mcp/README.md | 2 +- .../beads-mcp/src/beads_mcp/models.py | 2 +- .../beads-mcp/src/beads_mcp/server.py | 8 +- integrations/beads-mcp/src/beads_mcp/tools.py | 4 +- internal/types/types.go | 23 ++-- internal/types/types_test.go | 10 ++ 16 files changed, 156 insertions(+), 25 deletions(-) create mode 100644 claude-plugin/commands/decision.md 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 + +<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`) 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, ""},