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

> Explore the 12 immutable core issue types in the Beads issue model, including bug, feature, epic, and spike. Master the canonical taxonomy to streamline your development workflow with this complete developer guide.

- Repository: [Gas Town Hall/beads](https://github.com/gastownhall/beads)
- Tags: deep-dive
- Published: 2026-04-27

---

**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](https://github.com/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`](https://github.com/gastownhall/beads/blob/main/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`](https://github.com/gastownhall/beads/blob/main/internal/types/types.go) before creating the issue object.

To create a standard bug report:

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

```

To request a new capability:

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

```

To record an architectural decision:

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

```

To initiate a threaded conversation between agents:

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

```

To schedule a time-boxed investigation:

```bash
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.

```go
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`](https://github.com/gastownhall/beads/blob/main/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`](https://github.com/gastownhall/beads/blob/main/internal/tracker/github/mapping.go)** and **[`internal/tracker/jira/fieldmapper.go`](https://github.com/gastownhall/beads/blob/main/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`](https://github.com/gastownhall/beads/blob/main/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`](https://github.com/gastownhall/beads/blob/main/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.

```bash
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.