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>
8 KiB
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:
keyis a plan-local symbolic name; the result maps each key to the minted issue ID.idoptionally pins an explicit issue ID instead (must match the database prefix, likebd create --id).parent_key(a plan node key) orparent_id(an existing issue ID) adds aparent-childdependency on the created node.parentandestimateare accepted aliases forparent_keyandestimated_minutes; the canonical field wins when both spellings are set.statussets the initial status (defaultopen, ordeferredwhendefer_untilis in the future). Nodes createdclosedgetclosed_atauto-filled. Timestamps are RFC3339; relative forms like+6hare not accepted in plans.ephemeral/no_historyoverride the plan-wide--ephemeral/--no-historyflags per node (mutually exclusive per node; in proxied-server mode the effective storage class must be uniform across the plan).event_kind,actor,target, andpayloadrequire"type": "event".metadataaccepts arbitrary JSON values;metadata_refsvalues 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:
typedefaults toblocks.parent_key/parent_idon nodes already createparent-childedges; don't repeat them inedges.gate(all-children|any-children) andspawner_key/spawner_idattach fanout-gate metadata towaits-foredges, mirroring--waits-for/--waits-for-gate. Thetoendpoint of awaits-foredge is the spawner (gate evaluation watches its children), sospawner_keymust matchto_keyandspawner_idmust matchto_id; they exist to make plans self-documenting. Since an explicitto_idoverridesto_keyas the target,spawner_keycannot be combined withto_id— usespawner_id.- Edges with ready-work-affecting types (
blocks,waits-for, …) may not duplicate or reverse aparent_key/parent_idrelationship, and a parent may not be connected to its own child through them. thread_idthreads 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.