beads/docs/cli-reference/create.md
Isis Anisoptera aadd21c40b docs(cli): move the graph plan schema into an embedded doc supplement
The --graph schema section was hand-written into the generated
docs/CLI_REFERENCE.md, which the byte-exact drift gate rejects and any
regeneration (including the docs-autofix bot) would erase — breaking
TestDocsGraphPlanExampleValidates. Long: strings can't carry it either:
escapeMDXText would mangle the fenced JSON example.

Add a command doc-supplement mechanism: raw Markdown embedded from
cmd/bd/help_supplements/ and appended after a command's flags by the docs
generator, so regeneration reproduces the section byte-for-byte in both
CLI_REFERENCE.md and the per-command create.md page. Document the
parent/estimate aliases and their precedence while moving the text.
Regeneration also restores the four per-command pages (heartbeat,
migrate-personal, reclaim, unclaim) that docs.json already listed but the
committed tree was missing.

Co-Authored-By: Claude Fable 5 <noreply@anthropic.com>
2026-07-18 11:52:57 -07:00

8 KiB

title description
bd create Create a new issue (or batch from markdown/graph JSON)

{/* AUTO-GENERATED: do not edit manually */}

Generated from bd help --doc create.

Create a new issue (or batch from markdown/graph JSON)

bd create [title] [flags]

Aliases: new

Flags:

      --acceptance string       Acceptance criteria
      --append-notes string     Append to existing notes (with newline separator)
  -a, --assignee string         Assignee
      --body-file string        Read description from file (use - for stdin)
      --context string          Additional context for the issue
      --defer string            Defer until date (issue hidden from bd ready until then). Same formats as --due
      --deps strings            Dependencies in format 'type:id' or 'id' (e.g., 'discovered-from:bd-20,blocks:bd-15' or 'bd-20')
  -d, --description string      Issue description
      --design string           Design notes
      --design-file string      Read design from file (use - for stdin)
      --dry-run                 Preview what would be created without actually creating
      --due string              Due date/time. Formats: +6h, +1d, +2w, tomorrow, next monday, 2025-01-15
      --ephemeral               Create as ephemeral (short-lived, subject to TTL compaction)
  -e, --estimate int            Time estimate in minutes (e.g., 60 for 1 hour)
      --event-actor string      Entity URI who caused this event (requires --type=event)
      --event-category string   Event category (e.g., patrol.muted, agent.started) (requires --type=event)
      --event-payload string    Event-specific JSON data (requires --type=event)
      --event-target string     Entity URI or bead ID affected (requires --type=event)
      --external-ref string     External reference (e.g., 'gh-9', 'jira-ABC', Linear URL)
  -f, --file string             Create multiple issues from markdown file
      --force                   Force creation even if prefix doesn't match database prefix
      --graph string            Create a graph of issues with dependencies from JSON plan file
      --id string               Explicit issue ID (e.g., 'bd-42' for partitioning)
  -l, --labels strings          Labels (comma-separated)
      --metadata string         Set custom metadata (JSON string or @file.json to read from file)
      --mol-type string         Molecule type: swarm (multi-agent), patrol (recurring ops), work (default)
      --no-history              Skip Dolt commit history without making GC-eligible (for permanent agent beads)
      --no-inherit-labels       Don't inherit labels from parent issue
      --notes string            Additional notes
      --parent string           Parent issue ID for hierarchical child (e.g., 'bd-a3f8e9')
  -p, --priority string         Priority (0-4 or P0-P4, 0=highest) (default "2")
      --repo string             Target repository for issue (overrides auto-routing)
      --silent                  Output only the issue ID (for scripting)
      --skills string           Required skills for this issue
      --spec-id string          Link to specification document
      --stdin                   Read description from stdin (alias for --body-file -)
      --title string            Issue title (alternative to positional argument)
  -t, --type string             Issue type (bug|feature|task|epic|chore|decision); custom types require types.custom config; aliases: enhancement/feat→feature, dec/adr→decision (default "task")
      --validate                Validate description contains required sections for issue type
      --waits-for string        Spawner issue ID to wait for (creates waits-for dependency for fanout gate)
      --waits-for-gate string   Gate type: all-children (wait for all) or any-children (wait for first) (default "all-children")
      --wisp-type string        Wisp type for TTL-based compaction: heartbeat, ping, patrol, gc_report, recovery, error, escalation

Graph plan schema (--graph):

bd create --graph plan.json creates a whole issue graph atomically from a JSON plan. Node field names follow the issue model's JSON tags (the same names bd show --json emits), and every field single-issue bd create can set is addressable from a plan — plus an initial status and pinned, which bd create has no flags for:

{
  "commit_message": "optional Dolt commit message",
  "nodes": [
    {
      "key": "api",
      "title": "Design the API",
      "type": "task",
      "description": "…", "design": "…", "acceptance_criteria": "…", "notes": "…",
      "status": "in_progress",
      "priority": 1,
      "assignee": "alice", "assign_after_create": false,
      "owner": "alice@example.com",
      "labels": ["backend"],
      "estimated_minutes": 45,
      "due_at": "2030-01-02T15:04:05Z",
      "defer_until": "2030-01-01T00:00:00Z",
      "spec_id": "bd-spec1", "external_ref": "gh-42",
      "metadata": {"any": "json", "count": 3},
      "metadata_refs": {"tracker": "impl"},
      "id": "bd-a1b2c3",
      "ephemeral": false, "no_history": false,
      "wisp_type": "heartbeat", "mol_type": "swarm",
      "pinned": false
    },
    { "key": "impl", "title": "Implement it", "parent_key": "api" },
    { "key": "gate", "title": "Fanout gate" },
    { "key": "launch", "title": "Launch announced", "type": "event",
      "event_kind": "agent.started", "actor": "agent://a", "target": "bead://b", "payload": "{}" }
  ],
  "edges": [
    { "from_key": "gate", "to_key": "api", "type": "blocks" },
    { "from_key": "gate", "to_key": "impl", "type": "waits-for",
      "gate": "any-children", "spawner_key": "impl" }
  ]
}

Node notes:

  • key is a plan-local symbolic name; the result maps each key to the minted issue ID. id optionally pins an explicit issue ID instead (must match the database prefix, like bd create --id).
  • parent_key (a plan node key) or parent_id (an existing issue ID) adds a parent-child dependency on the created node.
  • parent and estimate are accepted aliases for parent_key and estimated_minutes; the canonical field wins when both spellings are set.
  • status sets the initial status (default open, or deferred when defer_until is in the future). Nodes created closed get closed_at auto-filled. Timestamps are RFC3339; relative forms like +6h are not accepted in plans.
  • ephemeral / no_history override the plan-wide --ephemeral / --no-history flags per node (mutually exclusive per node; in proxied-server mode the effective storage class must be uniform across the plan).
  • event_kind, actor, target, and payload require "type": "event".
  • metadata accepts arbitrary JSON values; metadata_refs values name other node keys and are replaced with their minted IDs after creation.
  • Unlike bd create --parent, graph children do not inherit parent labels and receive flat (non-hierarchical) IDs; plans are explicit artifacts.

Edge notes:

  • type defaults to blocks. parent_key/parent_id on nodes already create parent-child edges; don't repeat them in edges.
  • gate (all-children | any-children) and spawner_key/spawner_id attach fanout-gate metadata to waits-for edges, mirroring --waits-for/--waits-for-gate. The to endpoint of a waits-for edge is the spawner (gate evaluation watches its children), so spawner_key must match to_key and spawner_id must match to_id; they exist to make plans self-documenting. Since an explicit to_id overrides to_key as the target, spawner_key cannot be combined with to_id — use spawner_id.
  • Edges with ready-work-affecting types (blocks, waits-for, …) may not duplicate or reverse a parent_key/parent_id relationship, and a parent may not be connected to its own child through them.
  • thread_id threads conversation edges (e.g. replies-to).

Comments cannot be created from a plan; use bd comments add after creation. Model fields without bd create flags (sender, work_type, is_template, await_*, bonded_from, source_*) are likewise not settable from plans.