Get the FREE Ultimate OpenClaw Setup Guide →

bmad-architect

Scanned
npx machina-cli add skill xmm/codex-bmad-skills/bmad-architect --openclaw
Files (1)
SKILL.md
4.7 KB

BMAD Architect

Trigger Intents

  • bmad:architecture
  • bmad:gate-check

Workflow Variants

  1. architecture
  • Produce architecture decisions, components, interfaces, and data model.
  1. gate-check
  • Validate architecture quality and requirement coverage before implementation.

Mode selection:

  • Run architecture when docs/bmad/architecture.md does not exist or requirements changed materially.
  • Run gate-check when architecture exists and the team needs a formal implementation-readiness decision.

Inputs

  • planning artifact (docs/bmad/prd.md or docs/bmad/tech-spec.md)
  • architecture artifact (docs/bmad/architecture.md) for gate-check mode
  • bmad/project.yaml level and constraints
  • known integration, compliance, and scalability constraints

Language Guard (Mandatory)

Enforce language selection separately for chat responses and generated artifacts.

Chat language (communication_language) fallback order:

  1. language.communication_language from bmad/project.yaml
  2. 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:

  1. language.document_output_language from bmad/project.yaml
  2. 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 architecture or gate-check, read REFERENCE.md first. Treat REFERENCE.md as required context, then load relevant resources and templates.

Output Contract

  • architecture -> docs/bmad/architecture.md
  • gate-check -> docs/bmad/gate-check.md

Core Workflow

  1. Define system boundaries and architecture drivers.
  2. Select architecture pattern and justify trade-offs.
  3. Design components, APIs, and data model.
  4. Map NFRs to concrete controls and design choices.
  5. Run gate-check using criteria from resources/gate-check-criteria.md and report pass/fail gaps.

Gate-Check Criteria

Load and apply resources/gate-check-criteria.md as the single source of truth for:

  • coverage metric formulas
  • blocker classification rules
  • PASS / CONDITIONAL PASS / FAIL thresholds

Gate-Check Artifact Format

Always save docs/bmad/gate-check.md using templates/gate-check.template.md.

Required sections:

  • Executive Summary with decision (PASS, CONDITIONAL PASS, or FAIL)
  • Requirements Coverage (FR and NFR totals, coverage percentages, missing items)
  • Architecture Quality Assessment (checklist score and failed checks)
  • Issues (Blockers, Major Concerns, Minor Issues)
  • Recommendations
  • Gate Decision (threshold comparison and rationale)
  • Next Steps
  • Appendix with detailed FR/NFR mapping evidence

Script Selection

  • architecture mode: 
    bash scripts/nfr-checklist.sh
bash scripts/validate-architecture.sh docs/bmad/architecture.md
  • gate-check mode: 
    bash scripts/validate-architecture.sh docs/bmad/architecture.md
bash scripts/nfr-checklist.sh

Template Map

  • templates/architecture.template.md

  • Why: full architecture structure with design decisions and NFR mapping.

  • templates/gate-check.template.md

  • Why: deterministic gate-check report format with objective pass criteria.

Reference Map

  • REFERENCE.md

  • Must read first for architecture workflow details and design decision quality criteria.

  • resources/architecture-patterns.md

  • Use when selecting monolith, modular monolith, microservices, or other patterns.

  • resources/nfr-mapping.md

  • Use to map performance, security, scalability, and reliability requirements.

  • resources/gate-check-criteria.md

  • Use as mandatory criteria source for gate-check scoring and decision thresholds.

Quality Gates

  • architecture decisions trace back to requirements
  • interfaces and data model are explicit
  • NFR coverage is documented, not implied
  • critical risks and mitigations are listed
  • implementation can proceed without unresolved blockers

Source

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

Overview

This skill helps BMAD teams produce architecture decisions, components, interfaces, and data models, and to perform formal gate-checks for implementation readiness. It orchestrates planning artifacts, architecture artifacts, and project constraints to ensure requirement coverage and quality before coding.

How This Skill Works

BMAD Architect reads planning and architecture artifacts, enforces the language guard for outputs, and follows the core workflow to define system boundaries, drivers, and patterns. It maps non-functional requirements to concrete controls, designs APIs and data models, and then runs gate-check criteria to issue a PASS, CONDITIONAL PASS, or FAIL with gaps identified.

When to Use It

  • When docs/bmad/architecture.md is missing or the requirements have changed materially, to generate up-to-date architecture decisions.
  • When a formal implementation-readiness gate-check is needed before proceeding to implementation.
  • When you have a planning artifact (docs/bmad/prd.md or docs/bmad/tech-spec.md) and need a concrete architecture translation.
  • When validating integration, compliance, and scalability constraints against the proposed design.
  • When you require a traceable, reference-driven architecture quality assessment aligned to gate-check criteria.

Quick Start

  1. Step 1: Prepare inputs (docs/bmad/prd.md or docs/bmad/tech-spec.md) and ensure REFERENCE.md is loaded.
  2. Step 2: Run architecture mode to generate docs/bmad/architecture.md and decision records.
  3. Step 3: If needed, run gate-check mode to produce docs/bmad/gate-check.md with the implementation-readiness verdict.

Best Practices

  • Load REFERENCE.md before modeling and ensure traceability from requirements to design decisions.
  • Explicitly define system boundaries, architecture drivers, and the chosen pattern with justified trade-offs.
  • Map each NFR to concrete design controls and document trade-offs visible to stakeholders.
  • Document interfaces, APIs, and data models with clear mapping to requirements and constraints.
  • Run gate-check after architecture to surface gaps, blockers, and risks prior to implementation.

Example Use Cases

  • Architect a BMAD module with clearly defined components, interfaces, and a coherent data model.
  • Perform a gate-check to determine whether the architecture meets FR/NFR coverage and constraints.
  • Conduct a trade-off analysis between modular vs monolithic designs for a BMAD service.
  • Design data integration patterns with external systems while satisfying compliance constraints.
  • Map security, reliability, and scalability NFRs to concrete architectural decisions.

Frequently Asked Questions

Add this skill to your agents
Sponsor this space

Reach thousands of developers ↗