Skills › BMAD Method › bmad-ux › headless-schemas.md

headless-schemas.md

84 lines · skills/bmad-ux/assets/headless-schemas.md at bd70c64

Open on GitHub

1# Headless Mode Output Examples

3Every headless run ends with one of these payloads. Omit keys for artifacts not produced.

Headless Mode Output Examples

Every headless run ends with one of these payloads. Omit keys for artifacts not produced.

Raw lines 1 to 4

5## Common fields

7- `status` — `"complete"`, `"blocked"`, or `"partial"`

8- `intent` — `"create"`, `"update"`, or `"validate"` (matches the detected intent)

9- `reason` — required when `status` is `"blocked"`; one-sentence explanation

10- `assumptions` — array of inferred values that were not directly confirmed by inputs

11- `open_questions` — array of items that need a human decision before the artifact can be considered final

Common fields

status — "complete", "blocked", or "partial"
intent — "create", "update", or "validate" (matches the detected intent)
reason — required when status is "blocked"; one-sentence explanation
assumptions — array of inferred values that were not directly confirmed by inputs
open_questions — array of items that need a human decision before the artifact can be considered final

Raw lines 5 to 12

13## Create

15```json

16{

17 "status": "complete",

18 "intent": "create",

19 "design": "{doc_workspace}/DESIGN.md",

20 "experience": "{doc_workspace}/EXPERIENCE.md",

21 "memlog": "{doc_workspace}/.memlog.md",

22 "working_artifacts": ["{doc_workspace}/.working/color-themes-1.html"],

23 "promoted_artifacts": {

24 "mockups": ["{doc_workspace}/mockups/direction-calm-sage.html"],

25 "wireframes": ["{doc_workspace}/wireframes/ia-2026-05-19.excalidraw"]

26 },

27 "open_questions": [],

28 "assumptions": [],

29 "external_handoffs": [

30 {"directive": "Confluence upload", "tool": "corp:confluence_upload", "url": "https://confluence.corp/DESIGN/123", "status": "ok"}

31 ]

32}

33```

35The `working_artifacts` and `promoted_artifacts` keys are optional and omitted entirely when empty. Headless Create runs default to not enabling creative tools — both keys are typically absent in headless output unless the caller enabled them.

Create

{
  "status": "complete",
  "intent": "create",
  "design": "{doc_workspace}/DESIGN.md",
  "experience": "{doc_workspace}/EXPERIENCE.md",
  "memlog": "{doc_workspace}/.memlog.md",
  "working_artifacts": ["{doc_workspace}/.working/color-themes-1.html"],
  "promoted_artifacts": {
    "mockups": ["{doc_workspace}/mockups/direction-calm-sage.html"],
    "wireframes": ["{doc_workspace}/wireframes/ia-2026-05-19.excalidraw"]
  },
  "open_questions": [],
  "assumptions": [],
  "external_handoffs": [
    {"directive": "Confluence upload", "tool": "corp:confluence_upload", "url": "https://confluence.corp/DESIGN/123", "status": "ok"}
  ]
}

The working_artifacts and promoted_artifacts keys are optional and omitted entirely when empty. Headless Create runs default to not enabling creative tools — both keys are typically absent in headless output unless the caller enabled them.

Raw lines 13 to 36

37## Update

39```json

40{

41 "status": "complete",

42 "intent": "update",

43 "design": "{doc_workspace}/DESIGN.md",

44 "experience": "{doc_workspace}/EXPERIENCE.md",

45 "memlog": "{doc_workspace}/.memlog.md",

46 "changes_summary": "1-3 sentences describing what changed and why",

47 "conflicts_with_prior_decisions": [],

48 "open_questions": [],

49 "external_handoffs": [

50 {"directive": "Confluence upload", "tool": "corp:confluence_upload", "url": "https://confluence.corp/DESIGN/123", "status": "ok"}

51 ]

52}

53```

Update

{
  "status": "complete",
  "intent": "update",
  "design": "{doc_workspace}/DESIGN.md",
  "experience": "{doc_workspace}/EXPERIENCE.md",
  "memlog": "{doc_workspace}/.memlog.md",
  "changes_summary": "1-3 sentences describing what changed and why",
  "conflicts_with_prior_decisions": [],
  "open_questions": [],
  "external_handoffs": [
    {"directive": "Confluence upload", "tool": "corp:confluence_upload", "url": "https://confluence.corp/DESIGN/123", "status": "ok"}
  ]
}

Raw lines 37 to 54

55## Validate

57```json

58{

59 "status": "complete",

60 "intent": "validate",

61 "validation_report": "{doc_workspace}/validation-report.md",

62 "findings_summary": {

63 "critical": 0,

64 "high": 0,

65 "medium": 0,

66 "low": 0

67 },

68 "offer_to_update": true

69}

70```

72`validation_report` is always written for Validate intent — the path here is required, not optional.

Validate

{
  "status": "complete",
  "intent": "validate",
  "validation_report": "{doc_workspace}/validation-report.md",
  "findings_summary": {
    "critical": 0,
    "high": 0,
    "medium": 0,
    "low": 0
  },
  "offer_to_update": true
}

validation_report is always written for Validate intent — the path here is required, not optional.

Raw lines 55 to 73

74## Blocked

76```json

77{

78 "status": "blocked",

79 "intent": "update",

80 "reason": "Change signal ambiguous — could be a brand refresh or an accessibility audit response; no inferred direction"

81}

82```

84Always include the intent (best-guess if not certain) and a one-sentence `reason`.

Blocked

{
  "status": "blocked",
  "intent": "update",
  "reason": "Change signal ambiguous — could be a brand refresh or an accessibility audit response; no inferred direction"
}

Always include the intent (best-guess if not certain) and a one-sentence reason.

Raw lines 74 to 84