Core Issue Types in the Beads Issue Model: The Complete Developer Guide

Beads defines 12 immutable core issue types—including bug, feature, epic, spike, and molecule—as constants in the Go source, providing the canonical taxonomy used by the CLI, UI, and external tracker integrations.

The Beads project management tool (gastownhall/beads) organizes every unit of work through a strictly defined taxonomy of core issue types. These built-in categories serve as the foundation for the entire workflow, determining how issues are validated, displayed, and synchronized with external trackers like GitHub and Jira. Understanding the core issue types in the Beads issue model is essential for writing valid issues and configuring automation rules.

Where Core Issue Types Are Defined in Source Code

Beads declares its canonical issue types as typed constants in the Go source file internal/types/types.go. According to the gastownhall/beads source code, lines 524–535 contain the complete enumeration of available types as the IssueType constants. The system also defines a separate TypeEvent constant for internal system events, though this is reserved for backend use and not exposed as a user-facing issue type.

The Complete Catalog of Core Issue Types

The Beads issue model recognizes twelve distinct core types, each represented by a specific constant in the codebase. These are immutable definitions that cannot be overridden or extended by end users.

• bug (TypeBug): Defects or problems that need fixing.

• feature (TypeFeature): New capabilities or enhancements.

• task (TypeTask): Small pieces of work, generally implementation-level.

• epic (TypeEpic): Large bodies of work that are broken down into child issues.

• chore (TypeChore): Maintenance-type work that is not user-facing.

• decision (TypeDecision): Recorded choices that affect the project’s direction.

• message (TypeMessage): Threaded communication between agents or humans.

• molecule (TypeMolecule): Internal coordination primitive for swarming agents.

• gate (TypeGate): Async coordination primitive used for gates.

• spike (TypeSpike): Time-boxed investigation to reduce uncertainty.

• story (TypeStory): User-oriented description of a feature.

• milestone (TypeMilestone): Marker that groups a set of related issues, containing no work itself.

Using Core Issue Types in the Beads CLI

The bd command-line interface accepts these type values directly via the --type flag. The CLI validates the input against the constants defined in internal/types/types.go before creating the issue object.

To create a standard bug report:

bd create "Crash on startup" --type bug --priority 0

To request a new capability:

bd create "Add dark-mode support" --type feature --priority 1

To record an architectural decision:

bd create "Choose PostgreSQL over MySQL" --type decision

To initiate a threaded conversation between agents:

bd create "Review of the new caching strategy" --type message --thread

To schedule a time-boxed investigation:

bd create "Investigate GraphQL vs REST for the API" --type spike --priority 2

Programmatic Usage in Go

When constructing issues programmatically, you must import the internal types package and assign the typed constant directly to the IssueType field. This ensures compile-time safety and prevents invalid type strings from entering the system.

import "github.com/gastownhall/beads/internal/types"

issue := types.Issue{
    ID:        "bd-1234",
    Title:     "Fix login race condition",
    IssueType: types.TypeBug,
    Priority:  0,
    Status:    types.StatusOpen,
}

The IssueType field accepts only the predefined constants (e.g., types.TypeBug, types.TypeSpike), not raw strings, enforcing the core issue type contract at the type system level.

Validation and External Tracker Mapping

The core issue types in the Beads issue model drive validation logic and external integrations. The file internal/validation/template.go enforces that created issues contain the required sections for their specific type. For example, a decision type might require a "Consequences" section, while a bug requires "Reproduction Steps."

External tracker mappings in internal/tracker/github/mapping.go and internal/tracker/jira/fieldmapper.go translate between Beads core types and native labels or fields in GitHub and Jira. This ensures that when you create a TypeChore in Beads, it maps correctly to a corresponding label or issue type in the integrated platform.

Summary

• Beads defines 12 core issue types as immutable constants in internal/types/types.go (lines 524–535).
• The complete set includes bug, feature, task, epic, chore, decision, message, molecule, gate, spike, story, and milestone.
• TypeEvent exists for internal system events but is not exposed as a user-facing issue type.
• The bd CLI validates type arguments against these constants using the --type flag.
• Validation logic in internal/validation/template.go ensures issues contain type-specific required sections.
• External tracker integrations map between Beads core types and native fields in GitHub and Jira.

Frequently Asked Questions

Can I add custom issue types to Beads?

No, the core issue types in the Beads issue model are fixed constants defined in the source code. You cannot create custom types through configuration; the system recognizes only the 12 built-in types plus the internal TypeEvent. Any categorization beyond these primitives must be handled through labels, tags, or custom fields within the existing type structure.

What is the difference between an epic and a milestone in Beads?

An epic (TypeEpic) represents a large body of work that is actively broken down into child issues and contains actionable tasks. A milestone (TypeMilestone) serves as a temporal or thematic marker that groups related issues together but carries no work itself—it functions purely as an organizational container for tracking progress toward a goal.

How do I create a spike issue using the Beads CLI?

Use the bd create command with the --type spike flag and optionally assign a priority. Spikes are time-boxed research issues designed to reduce uncertainty before committing to implementation.

bd create "Research OAuth2 providers" --type spike --priority 1

Why is the message type considered a core issue type rather than a comment?

Beads treats message (TypeMessage) as a first-class issue type to enable threaded, persistent communication between agents or humans that can be tracked, prioritized, and assigned like any other work unit. Unlike ephemeral comments, message-type issues exist in the backlog, support threading logic via the --thread flag, and can integrate with notification systems, making them formal coordination primitives rather than simple annotations.

{
  "mcpServers": {
    "instagit": {
      "command": "npx",
      "args": ["-y", "instagit@latest"]
    }
  }
}