What is BMAD Shared used for?

It provides shared workflow state contracts and helper scripts for BMAD, enabling consistent state management across orchestrator and phase skills.

What files and scripts are involved?

Key artifacts include YAML contracts (workflows.registry.yaml, REFERENCE.md, helpers.md) and scripts like load-project-config.sh, load-global-config.sh, update-workflow-status.sh, and next-workflow.sh.

How do I ensure deterministic updates?

Follow the Usage Rules and use yq v4+ for all YAML reads/writes; keep updates idempotent and rely on the provided scripts for state transitions.

bmad-shared

Scanned

npx machina-cli add skill xmm/codex-bmad-skills/bmad-shared --openclaw

Files (1)

SKILL.md

3.0 KB

BMAD Shared

Purpose

Provide shared workflow state contracts and helper scripts for all BMAD skills.

Language Guard (Mandatory)

Enforce language selection separately for chat responses and generated artifacts.

Chat language (communication_language) fallback order:

language.communication_language from bmad/project.yaml
English

Rules for chat responses:

Use the resolved chat language for all assistant responses (questions, status updates, summaries, and handoff notes).
Do not switch chat language unless the user explicitly requests a different language in the current thread.

Artifact language (document_output_language) fallback order:

language.document_output_language from bmad/project.yaml
English

Rules for generated artifacts:

Use the resolved artifact language for all generated BMAD documents and structured artifacts.
write prose and field values in the resolved document language
avoid mixed-language requirement clauses with English modal verbs (for example, System shall followed by non-English text)
allow English acronyms/abbreviations in non-English sentences (for example, API, SLA, KPI, OAuth, WCAG)
Keep code snippets, CLI commands, file paths, and identifiers in their original technical form.

Mandatory Reference Load

Before executing shared helper workflows, read REFERENCE.md first. Treat REFERENCE.md as required context for state semantics and update rules.

Workflow Variants

config-read

Read project or global configuration safely.

status-update

Update workflow state after completion.

next-recommendation

Compute next intent from workflow state.

YAML Contract Files

workflows.registry.yaml
REFERENCE.md
Shared script semantics and state rules.
helpers.md
Shared implementation conventions and migration notes.

Script Selection

Current scripts:

Read project config:

bash scripts/load-project-config.sh bmad/project.yaml

Read global config:
```
bash scripts/load-global-config.sh
```

Update workflow state:

bash scripts/update-workflow-status.sh --workflow product_brief --status-file bmad/workflow-status.yaml

Recommend next workflow:

bash scripts/next-workflow.sh bmad/workflow-status.yaml

Compatibility wrappers:

scripts/load-config.sh -> wrapper to load-project-config.sh
scripts/update-status.sh -> wrapper to update-workflow-status.sh
scripts/check-phase.sh -> wrapper to next-workflow.sh

Usage Rules

prefer yq v4+ for all YAML reads and writes
keep updates deterministic and idempotent where possible
avoid ad-hoc parsing for nested YAML values

Quality Gates

YAML contract files remain backward-compatible within this branch
scripts return explicit errors for missing files or tools
state transitions update metrics and phase status consistently

Source

git clone https://github.com/xmm/codex-bmad-skills/blob/main/skills/bmad-shared/SKILL.mdView on GitHub

Overview

BMAD Shared provides reusable workflow state contracts and helper scripts for all BMAD skills. It includes YAML contracts and deterministic scripts used by the orchestrator and phase skills to coordinate progress and artifacts.

How This Skill Works

It enforces a Language Guard for chat responses and artifacts, loads project/global configs, and updates or reads workflow state via dedicated scripts. The workflow relies on REFERENCE.md for context and exposes compatibility wrappers to streamline usage across BMAD components.

When to Use It

When coordinating multiple BMAD skills (orchestrator and phase) that share state and contracts
When you need deterministic YAML contracts and state management for BMAD workflows
Before generating artifacts to ensure language and formatting rules are applied consistently
When updating workflow status or computing the next recommended workflow
When validating references and context via REFERENCE.md before execution

Quick Start

Step 1: Read REFERENCE.md to understand required state semantics
Step 2: Load configuration with bash scripts/load-project-config.sh bmad/project.yaml
Step 3: Update state or compute next steps with bash scripts/update-workflow-status.sh --workflow <name> --status-file <path> or bash scripts/next-workflow.sh bmad/workflow-status.yaml

Best Practices

Read REFERENCE.md before executing shared helper workflows to understand state semantics
Use yq v4+ for all YAML reads and writes to keep operations deterministic
Keep updates idempotent; avoid ad-hoc parsing of nested YAML values
Prefer the provided scripts (load-project-config.sh, update-workflow-status.sh, next-workflow.sh) for consistency
Audit changes against workflows.registry.yaml and helper documentation in helpers.md

Example Use Cases

Read project config: bash scripts/load-project-config.sh bmad/project.yaml
Read global config: bash scripts/load-global-config.sh
Update workflow state: bash scripts/update-workflow-status.sh --workflow product_brief --status-file bmad/workflow-status.yaml
Compute next workflow: bash scripts/next-workflow.sh bmad/workflow-status.yaml
Use compatibility wrappers like scripts/load-config.sh to run load-project-config.sh

Frequently Asked Questions

Add this skill to your agents