Writing a bmad-loop plugin

August 19, 2026 · View on GitHub

A plugin extends the bmad-loop orchestrator without touching its core loop. It can be as simple as a settings-only data file or as complex as the bundled Unity game-engine layer. A plugin can:

observe, veto, or mutate the run at every lifecycle stage (a hook bus);
contribute settings that render in the settings TUI and persist to policy;
inject its own workflow sessions at defined points in the dev/review cycle.

Plugins are folder-drop: a directory with a plugin.toml manifest (plus any helper scripts) dropped under .bmad-loop/plugins/<name>/. No registration, no install step. A plugin that ships in-process Python is loaded only when you trust it by name — dropping a folder in never runs code.

Already wrote a CLI adapter profile or the old [engine] block? Same idea — declarative TOML + optional scripts, discovered and overlaid. The plugin system generalizes both.

Quick start: the smallest plugin

A data-only plugin carries one setting and zero behavior. Create .bmad-loop/plugins/hello/plugin.toml:

[plugin]
name = "hello"
version = "1.0.0"
api_version = 1
description = "Smallest possible plugin."
author = "you"

[[settings]]
key = "greeting"
type = "str"
default = "hi"
label = "Greeting"
help = "Shown in the settings UI once this plugin is enabled."

That's a complete, loadable plugin. It has no [hooks] and no [python], so it runs no code and is byte-identical to "no plugin" at run time — it exists only to contribute a setting. This is the shape the bundled example plugin ships in.

A setting-only section appears in the TUI only once the plugin is enabled:

# .bmad-loop/policy.toml
[plugins]
enabled = ["hello"]

Distribution & discovery

Plugins are discovered from three sources, overlaid in precedence order (a later same-name plugin overrides an earlier one; a new name extends the set):

Source	Path	Precedence
Builtin	`bmad_loop/data/plugins/<name>/plugin.toml`	base
Entry point	`bmad_loop.plugins` group	reserved (see below)
Project-local	`<project>/.bmad-loop/plugins/<name>/plugin.toml`	highest

Each plugin lives in its own directory — that directory is the plugin's {scripts} root (see {scripts} substitution), so its manifest and helper scripts sit together.

Entry points are a documented future seam. discover() already yields an entry_point source between builtin and project, but _discover_entry_points() returns nothing today — folder-drop is the only live distribution path. When pip-installable plugins land, they slot in here with no change to authors or to discovery order (importlib.metadata selectable entry points, group bmad_loop.plugins). See src/bmad_loop/plugins/loader.py.

The manifest (`plugin.toml`)

Every plugin is one plugin.toml. Only [plugin] name + api_version are required; every section below is optional, so a plugin opts into exactly what it needs. The manifest parses into the immutable PluginManifest (src/bmad_loop/plugins/model.py).

`[plugin]` — metadata

Field	Type	Default	Purpose
`name`	string	—	Required. Plugin id; the directory name; the `[plugins.<name>]` key.
`api_version`	int	—	Required. Plugin-API version this manifest targets (currently `1`).
`version`	string	`0.0.0`	Your plugin's own version.
`description`	string	`""`	One line; shown in tooling.
`author`	string	`""`	Attribution.
`priority`	int	`0`	Cross-plugin ordering at a shared stage; lower runs first, then load order.
`seed_files`	list	`[]`	Project-relative gitignored files to copy into each isolated worktree.
`seed_globs`	list	`[]`	Project-relative glob patterns to expand + copy into each worktree.

seed_files / seed_globs must be project-relative (an absolute path is rejected at load). They let a plugin prime an isolated checkout with gitignored paths it needs — e.g. the Unity plugin seeds an MCP-generated skill tree.

`[[settings]]` — settings schema

Each entry contributes one setting. See Settings for the full reference.

[[settings]]
key = "strict"        # required; unique within the plugin
type = "bool"         # bool | int | float | str | select
default = false
label = "Strict mode" # TUI label (falls back to the key)
help = "..."          # TUI help text
# select-only:
# options = ["a", "b"]
# numeric hints (int/float):
# min = 0
# max = 10

`[hooks.<stage>]` — declarative (out-of-process) hooks

A shell command bound to a lifecycle stage. See Hooks.

[hooks.pre_session]
cmd = 'python3 "{scripts}/probe.py"'
timeout_sec = 120          # default 120; must be >= 1
blocking = true            # non-zero exit vetoes (defers) the unit
fail_closed = false        # default: a hook *error* (timeout/launch) fails open

`[python]` — in-process module (trust-gated)

[python]
module = "hooks.py"        # plugin-relative file
class = "MyPlugin"         # subclass of bmad_loop.plugins.Plugin (default "Plugin")

Declaring [python] makes the whole plugin trust-gated: the module is never imported unless the plugin is in [plugins] enabled. See Trust.

`[workflows.<name>]` — provided workflows

An extra agent session injected at a stage. See Workflows.

[workflows.lint-sweep]
stage = "post_dev_phase"   # post_dev_phase | post_review_result | pre_commit_gate
role = "dev"               # dev | review
prompt = "/lint-sweep {story_key}"
blocking = false           # true: a failed session defers the unit

Declare <name>_enabled / <name>_blocking settings to let operators disable a step or flip its gate per run — see Making a workflow configurable.

`{scripts}` substitution

In any hook cmd or workflow prompt, {scripts} expands to the plugin's own directory — so a plugin references its bundled scripts without hardcoding a path that breaks across machines or between a builtin and a project-local copy.

Trust & safety

There are two trust tiers, by design:

Declarative tier (always runs). A data-only or declarative plugin — settings + [hooks.<stage>] shell commands — loads and runs as soon as it is discovered. This is the same risk surface as the old engine.toml *_cmd hooks or a project's verify commands: operator-authored shell, trusted by virtue of living in the repo.
In-process tier (trust-gated). A plugin that declares a [python] module is never imported or executed unless its name is in:
```
[plugins]
enabled = ["my-plugin"]
```
Dropping a [python] plugin folder in never runs its code. The module (and anything it provides that depends on the module — its on_<stage> handlers, its validate, and its provided workflows) stays inert until you list it. An un-enabled [python] plugin is recorded plugin-untrusted in the run journal.

Failure isolation. Every hook — subprocess or Python — is wrapped. A Python handler that raises is caught (except Exception only — RunStopped/SIGTERM as BaseException always propagate), journalled plugin-error, and the offending instance is disabled for the rest of the run. The run survives. A blocking declarative hook fails open by default (an error lets the run continue; only a clean non-zero exit vetoes); set fail_closed = true to make any failure defer the unit. An in-process handler can opt into the same by setting fail_closed = True on its class.

Versioning. Every manifest declares api_version. The framework supports a set of versions (SUPPORTED_API). A builtin with an unsupported version is a hard error (a packaging bug we shipped); a third-party one is skipped with a warning (plugin-skipped) so a stale drop-in can never take a run down.

Settings

A [[settings]] entry is presentation + validation metadata. The vocabulary matches the core settings fields exactly:

Field	Applies to	Meaning
`key`	all	Unique within the plugin; the policy + env key.
`type`	all	`bool` \| `int` \| `float` \| `str` \| `select`.
`default`	all	Value when the operator hasn't set one.
`label`	all	TUI label (falls back to `key`).
`help`	all	TUI help text.
`options`	`select`	Non-empty list of allowed string values.
`min`/`max`	`int`/`float`	Numeric bounds (widget hints).

Rendering. Once a plugin is enabled, its settings appear as their own section in the settings TUI (generated from the schema — see src/bmad_loop/settings_schema.py). They persist to a [plugins.<name>] table in policy.toml:

[plugins]
enabled = ["my-plugin"]

[plugins.my-plugin]
strict = true
mode = "b"

Reading a setting.

In an in-process plugin: self.settings["strict"] — the manifest defaults overlaid by the operator's [plugins.<name>] table.
In a declarative hook: each setting is exported as an environment variable BMAD_LOOP_SETTING_<KEY> (uppercased), already resolved.
Anywhere with a Policy: policy.plugin_setting("my-plugin", "strict", default).

Settings are data, not code — a plugin can carry [plugins.<name>] settings without being in enabled (the settings UI just won't surface a disabled plugin's section). Only the in-process [python] module is trust-gated.

Hooks

A hook binds a stage to behavior. The hook bus (src/bmad_loop/plugins/bus.py) fans each stage out to every bound plugin, in registry order (priority, then load order). A run with no plugin bound to a stage does no work for it (an O(1) fast-path) — zero-plugin runs stay byte-identical.

Declarative hooks

A [hooks.<stage>] shell command. The bus runs it with:

cwd = the unit's worktree (or repo root);

a BMAD_LOOP_* environment describing the run:

Var	Meaning
`BMAD_LOOP_STAGE`	the stage firing
`BMAD_LOOP_RUN_ID` / `BMAD_LOOP_RUN_DIR`	run identity
`BMAD_LOOP_REPO_ROOT` / `BMAD_LOOP_WORKTREE`	git roots
`BMAD_LOOP_STORY_KEY` / `BMAD_LOOP_ROLE` / `BMAD_LOOP_PHASE` / `BMAD_LOOP_BRANCH`	unit context
`BMAD_LOOP_AGENTS`	comma-separated CLI agent ids in the worktree
`BMAD_LOOP_PLUGIN`	your plugin's name
`BMAD_LOOP_SETTING_<KEY>`	each resolved setting

A blocking hook's non-zero exit vetoes (defers) the unit. A non-blocking hook is advisory (logged plugin-hook).

Mutating from a declarative hook. Emit a single JSON object on the last non-empty stdout line:

{
  "shared": { "scanned": 42 },
  "mutate": { "proposed_commit_message": "rewritten by my-plugin" },
  "veto": { "action": "defer", "reason": "lint failed" }
}

shared — merged into the cross-stage shared dict.
mutate — only whitelisted fields for the current stage.
veto — action ∈ skip | defer | pause. Supplying a veto replaces the implicit "non-zero exit = defer".

Any non-JSON output is treated as advisory log text.

In-process hooks

Subclass bmad_loop.plugins.Plugin and define on_<stage>(self, ctx) methods. The bus calls the handler for each stage you implement; you only mark the stages you handle, so the fast path holds for the rest.

from bmad_loop.plugins import Plugin

class MyPlugin(Plugin):
    fail_closed = False   # a raised handler is isolated; True also defers the unit

    def on_pre_commit(self, ctx):
        ctx.proposed_commit_message = f"{ctx.proposed_commit_message}\n\nShipped-by: me"

Optionally override validate(self, policy) to reject an incompatible config at startup (raise PluginError) — e.g. a coupling between a plugin setting and a core policy field. This runs once before any stage; a raise fails the run fast (it is a deliberate config rejection, not isolated like a hook bug).

Don't do expensive or side-effecting work in __init__. Construction happens at registry-build time, and a raised exception there disables the instance.

The `HookContext`

Every hook receives one HookContext (src/bmad_loop/plugins/context.py) for the stage. It carries:

Read-only facts (properties, no setter): run_id, story_key, epic, phase, attempt, role, worktree, branch, repo_root, run_dir, agents, result_json (a copy), session_status, verify_reason, decision_action, settings. Observe these; you can never rewrite history.
A mutable whitelist — assign only these, and only where the stage allows: proposed_prompt, proposed_env, proposed_feedback, proposed_commit_message, proposed_decision.
ctx.shared — a free-form, JSON-serializable dict that persists across stages (the engine backs it with RunState.plugin_shared, so it survives pause/resume). Use it to carry state between your own hooks.

Veto is ctx.veto(action, reason), with action:

Action	Routes onto the engine's existing…	Effect
`skip`	quiet retire	unit dropped (DEFERRED), no notification
`defer`	defer primitive	unit deferred + operator notified
`pause`	escalation	run pauses (raises `RunPaused`)

There is no new abort path — a veto maps onto control flow the engine already has. Multiple plugins can object; the bus collects every veto without short-circuit and resolves the most-conservative one (pause > defer > skip), so load order can never hide a severer objection. A post_*-stage veto is clamp-conservative only: a plugin can escalate the engine's own decision, never silence it.

Stage reference

Stages fire in pre_/post_ pairs around each unit of work. post_* stages see the mutations earlier pre_* stages made. The mutable surface column lists what a hook may assign at that stage; everything else on the context is read-only there.

Run / loop (no unit — a `pause` veto pauses the run)

Stage	When
`pre_run` / `post_run`	around the whole run
`pre_pick_next` / `post_pick_next`	around selecting the next story
`pre_epic_boundary` / `post_epic_boundary`	at an epic transition

Story / unit

Stage	When	Mutable surface
`pre_story` / `post_story`	around one story	veto (`pre_`)
`pre_worktree_setup` / `post_worktree_setup`	around isolated-worktree provisioning	—
`pre_ready_gate` / `post_ready_gate`	around the engine-ready gate	veto (`pre_`)
`pre_worktree_teardown` / `post_worktree_teardown`	around teardown (in a `finally`)	observe-only — a veto here cannot un-tear-down
`pre_rollback` / `post_rollback`	around a failed attempt's `git reset --hard` (only when a rollback actually runs)	observe-only — a veto here cannot block the reset
`pre_integrate`	before integrating a finished unit	—
`pre_merge` / `post_merge`	around the local branch merge	—

Dev

Stage	When	Mutable surface
`pre_dev_phase` / `post_dev_phase`	around the dev attempt loop	veto (`pre_`); `post_dev_phase` is a workflow injection point
`pre_dev_session`	before each dev session	`proposed_prompt`, `proposed_env`, veto
`post_dev_verify`	after dev or repair verification	—

post_dev_verify fires on both legs of the dev phase — once after the dev session's verification, and again after each repair session's — so a handler sees it more than once per story, not once. The two legs share one attempt counter bounded by [limits] max_dev_attempts, which is also the bound on how many times the stage can fire for one story. Write handlers to be idempotent and to key on the correlation fields below rather than on the story alone. It also fires on the way to a pause: an attempt whose session reported a CRITICAL escalation emits before the run stops, on either leg.

post_dev_verify exposes ctx.command_results: an immutable tuple of the per-command CommandResult records core just executed. Each has command, returncode, the existing merged bounded output_tail, and separate stdout and stderr strings. Those two are intended to be the streams essentially whole — they are not cut to [verify] stream_capture_kb, which bounds only what is written to disk — but they are not unbounded either: a hard 32 MiB per-stream ceiling applies, so a pathologically chatty command cannot grow the orchestrator's peak memory with the number of configured verify commands. When that ceiling cuts a stream the tail is what a plugin receives, and the matching journal record's stdout_bytes / stderr_bytes still report what the command emitted, so the cut is always detectable rather than silent. Ordinary suites never reach it. This is observation data only: a plugin cannot change the verifier's outcome or the commit decision. The run's journal.jsonl also records one verify-command-result entry per command with run/story/attempt/stage and verification-sequence correlation, output_tail, byte counts, and run-relative stdout_path / stderr_path pointers under the run's verify/ directory; full streams are not embedded in the journal. That store is deliberately separate from logs/, which holds coding-CLI pane captures named after session task ids and is read as such by the TUI.

Two more context fields say which verification the results came from, because nothing else on the context can: both the dev leg and the repair leg emit post_dev_verify from Phase.DEV_VERIFY, and ctx.attempt is one per-story counter the repair leg continues rather than restarts, so its value orders the two but names neither.

Field	Value
`ctx.verification_stage`	`"dev"` for the initial dev verification, `"fix"` for a repair one, `None` if none ran
`ctx.verification_sequence`	the story's 1-based ordinal for that pass, or `None` if it recorded nothing

Together they are the join key: the verify-command-result entries carrying this story_key + verification_stage + verification_sequence are exactly this context's results, one per record, ordered by command_index. The sequence is monotonic per story across a pause/resume — unlike attempt, which a human re-arm reuses — so it is safe to persist as a correlation id.

Read ctx.command_results == () together with verification_stage; on its own it is ambiguous:

verification_stage is None — no verify pass ran. Several causes land here and the empty tuple names none of them: the session did not complete (ctx.session_status), an earlier gate already failed the attempt — the dev-artifact check or the deferral harvest (ctx.verify_reason) — or the engine variant suppressed the pass for this leg (stories mode skips it on a plan-halt leg, which has no implementation to build).
stage set, verification_sequence is None — the pass ran and executed nothing, because [verify] commands is empty. No journal record exists either.
stage set, sequence an int — those commands ran, and each has a matching journal record.

What lands on disk is bounded by [verify] stream_capture_kb (default 256 KiB per stream): the tail is retained, and the record stays explicit about the cut — stdout_bytes / stderr_bytes are what the command emitted, stdout_captured_bytes / stderr_captured_bytes how much of that reached disk, and stdout_truncated / stderr_truncated their inequality. Both counts are UTF-8 lengths of the decoded stream, not file sizes: the files are written in text mode, so Windows newline translation makes the file larger there. Set the knob to 0 to retain nothing at all — no files are written and the pointers are null, but the record still lands with the full byte counts, because "nothing was retained" and "the command was silent" are different facts. Retaining is observation and never fails a run: if the write raises (ENOSPC, a read-only run dir, or a verify/ directory whose confinement cannot be established — the store refuses rather than write through a symlink a session planted), the pointer is null and capture_error carries the reason. A plugin reading these pointers must therefore treat both None and a missing file as normal, and consult *_truncated before assuming a file holds a command's whole output. Treat verifier output as potentially sensitive and store, upload, sign, or act on it only from an explicitly configured plugin.

The dev phase is the whole of this surface. [verify] commands also run at the review gate — verify_review / verify_review_stories / verify_review_bundle end on the same core classifier — and none of those runs are journalled or published to any hook. Five engine gates reach them: the converged review pass, the review-budget-exhaustion rescue, the review-timeout salvage, and both passes inside the skip-review commit path (which runs the gate again after a repair). bmad-loop confirm --reverify runs the commands too, out of band by construction — the run that parked the story is finished, so there is no journal to write to and no hook bus to emit on.

Two consequences a handler has to be written for:

verify-command-result entries are not a complete census of a run's verifier invocations. Every story that reaches a commit ran the commands at least once more than the records show. Never derive "the verifier ran N times" or "the last thing the verifier saw" from the journal — derive only "these are the dev-phase passes", which is what the records claim.
A green commit is not evidence that the last journalled pass was green, and a red journalled pass is not evidence the commit was blocked: a fix pass can fail and the story still commit after a later review-gate run that left no record. Correlate a decision with the dev-decision / fix-decision / review-result entries beside the results, not with the results alone.

The boundary is deliberate, not an oversight — the review leg would need its own hook stage rather than a second meaning for one named post_dev_verify — and is tracked as a follow-up in #656.

Review

Stage	When	Mutable surface
`pre_review_phase`	before the review loop	veto
`pre_review_session`	before each review session	`proposed_prompt`, `proposed_env`, veto
`post_review_session`	after each review session	—
`post_review_result`	after a review verdict	a workflow injection point
`pre_fix_session`	before a verify-repair session	`proposed_prompt`, `proposed_env`, veto

None of these carries the review gate's [verify] commands results — that gate runs the commands and retains nothing. See the boundary note above ### Review.

Commit

Stage	When	Mutable surface
`pre_commit_gate`	just before every commit, on every path	a workflow injection point; defer-safe (the unit may still defer)
`pre_commit`	before committing (after `pre_commit_gate`)	`proposed_commit_message`; only a `pause` veto is honored (the unit is mid-commit)
`post_commit`	after committing	—

Generic session boundary

Stage	When	Mutable surface
`pre_session`	before every session (after the role-specific `pre_*_session`, so it sees its mutations)	`proposed_prompt`, `proposed_env`, veto
`post_session`	after every session	—

Sweep (deferred-work cycle — bundles inherit all per-story stages)

Stage	When
`pre_sweep_cycle` / `post_sweep_cycle`	around a sweep cycle
`pre_triage_session` / `post_triage`	around triage
`pre_migrate_session` / `post_migrate`	around a legacy-ledger migration
`pre_close_resolved` / `post_close_resolved`	around closing resolved entries
`pre_decision` / `post_decision`	around a human-decision item
`pre_bundle` / `post_bundle`	around a deferred-work bundle
`pre_materialize_bundles` / `post_materialize_bundles`	around materializing bundles

Workflows (`[provides]`)

A workflow is the conservative form of custom orchestration: an extra agent session injected at a lifecycle stage, run through the engine's normal session machinery — no new pipeline stage. It is the right tool when you want an additional pass (a doc sync, a lint sweep, an extra reviewer) without rewriting the loop.

[workflows.doc-sync]
stage = "post_dev_phase"   # injection point (see below)
role = "review"            # which adapter runs it: dev | review
prompt = "Update CHANGELOG.md for story {story_key} if it introduced user-facing changes."
blocking = false           # true: a non-completed session defers the unit

Injection stages are deliberately limited to where the unit's worktree is live and the dev/review work is on disk: post_dev_phase (right after dev lands), post_review_result (after a review verdict — fires only when the orchestrator review loop actually runs; review.trigger = "recommended" skips it on stories whose dev session recommends no follow-up), and pre_commit_gate (unconditionally just before every commit — review, skip, and budget-rescue paths alike — so a session there evaluates the exact tree about to commit). pre_commit_gate is defer-safe: it fires before the unit enters COMMITTING, so a blocking workflow whose session doesn't complete still defers cleanly. Other stages lack a worktree or run after teardown.
prompt expands {story_key}, {run_id}, and {scripts}.
The orchestrator appends two sections to what you write, and appends them after the session gates fire, so a pre_workflow_session / pre_session prompt rewrite cannot strip them: a ## Sprint board prohibition — the same one dev and review prompts carry, because a workflow session runs while the orchestrator's own sprint-status.yaml advance is still uncommitted and must not be "fixed" or reverted (#437) — and the ## Completion signal contract naming the marker file the session must write before ending its turn. Write prompt as a self-contained instruction; do not restate either. (Stories mode has no board, so the first section is absent there.)
The injected session is a first-class session: it fires pre_workflow_session → pre_session → post_session, is recorded on the task, and counts toward the token budget. Its journal entries are workflow-start / workflow-end.
blocking: a blocking workflow whose session doesn't complete defers the unit (through the existing defer primitive). A non-blocking one is advisory.
A workflow from a [python] plugin is trust-gated along with the module: it fires only when the plugin is enabled. A workflow from a pure-declarative plugin fires whenever the plugin is discovered.

registry.provided_workflows() lists declared workflow names for introspection.

Making a workflow configurable

The blocking and (in effect) on/off state a workflow declares in its manifest are defaults. A plugin can let an operator tune them per run — disable a step or flip its gate — by declaring settings that follow a naming convention. No Python is required; the registry reads the resolved settings when it injects.

The convention, keyed on the workflow's name:

Setting key	Type	Effect
`<name>_enabled`	bool	When explicitly `false`, the step is dropped — no session runs.
`<name>_blocking`	bool	Overrides the manifest's `blocking` flag for that workflow.

Default semantics — absent settings change nothing. The overlay only acts on a setting that is present and (for _enabled) explicitly false; _blocking falls back to the manifest value when unset. A plugin that declares none of these settings is byte-identical to one written before the feature existed.

Declare the matching [[settings]] so the keys are first-class (typed, documented, surfaced in the settings UI) and operators can flip them from [plugins.<plugin>] in policy.toml:

# A gate step: generated advisory by default, an operator can make it block.
[workflows.nfr]
stage = "pre_commit_gate"
role = "review"
prompt = "Run the NFR assessment for the changes in {story_key}."
blocking = false              # manifest default: advisory

[[settings]]
key = "nfr_enabled"           # <name>_enabled  -> drop the step when false
type = "bool"
default = true
help = "Run the NFR workflow after review."

[[settings]]
key = "nfr_blocking"          # <name>_blocking -> override the blocking flag
type = "bool"
default = false
help = "Escalate the unit when the NFR gate is not satisfied."

An operator then opts in from policy:

[plugins.tea]
nfr_blocking = true           # flip the advisory gate to blocking
td_enabled   = false          # turn the test-design step off entirely

Interaction with the blocking / defer path. <name>_blocking feeds the same WorkflowSpec.blocking the engine already honors: a blocking workflow whose session does not complete defers the unit through the existing defer primitive (see Workflows above). The overlay only changes which value that flag holds at injection time — it adds no new control flow. (For quality gating on a workflow's output rather than its completion, do that in an in-process on_pre_commit hook; the manifest blocking flag only checks session completion.)

Disabling every step at a stage is free. When a setting turns off the last remaining workflow at a stage, that stage drops out of registry.workflow_stages() too, so the engine's O(1) per-stage injection guard skips it entirely — the same as if no workflow had ever been declared there.

Worked walkthrough: the `guardrails` plugin

The repo ships a complete example under examples/plugins/guardrails/ that exercises a setting, an observe hook, a veto gate, a commit-message mutation, and a provided workflow — in ~40 lines of Python plus a manifest. Build it yourself:

1. Make the folder. In your project:

.bmad-loop/plugins/guardrails/
  plugin.toml
  guardrails.py

2. Write the manifest (plugin.toml): metadata, a [python] module, two [[settings]] (trailer, forbid_epic), and one [workflows.doc-sync] bound to post_dev_phase. Copy it from the example.

3. Write the module (guardrails.py):

from bmad_loop.plugins import Plugin

class GuardrailsPlugin(Plugin):
    fail_closed = False

    def on_pre_story(self, ctx):
        # observe: count stories in the cross-stage shared dict
        ctx.shared["stories_seen"] = ctx.shared.get("stories_seen", 0) + 1

    def on_pre_dev_phase(self, ctx):
        # gate: skip a "parked" epic
        parked = int(self.settings.get("forbid_epic") or 0)
        if parked and ctx.epic == parked:
            ctx.veto("skip", f"epic {parked} is parked")

    def on_pre_commit(self, ctx):
        # mutate: append a trailer to the commit message
        trailer = str(self.settings.get("trailer") or "").strip()
        if trailer and trailer not in (ctx.proposed_commit_message or ""):
            base = (ctx.proposed_commit_message or "").rstrip()
            ctx.proposed_commit_message = f"{base}\n\n{trailer}" if base else trailer

4. Enable + configure in .bmad-loop/policy.toml:

[plugins]
enabled = ["guardrails"]

[plugins.guardrails]
trailer = "Automated-by: bmad-loop"
forbid_epic = 0           # set to an epic number to park it

5. Run. On the next bmad-loop run:

the settings TUI shows a guardrails section with trailer + forbid_epic;
each story increments stories_seen in the run's plugin_shared;
a story in the parked epic is skipped before its dev session;
after dev lands, the doc-sync workflow runs an extra review-role session;
each commit message gets the trailer appended.

Drop [python] from the manifest and guardrails from enabled, and the plugin goes completely inert — proof of the trust gate.

Platform portability

bmad-loop's core is portable Python, and the OS-specific work is quarantined behind seams (the tmux transport, the ProcessHost lifecycle, the hook interpreter — see Porting bmad-loop to a new OS). Plugin helper scripts are spawned under the orchestrator's own interpreter (sys.executable), not a PATH-resolved python3 — so a bundled script may import bmad_loop and reach those seams instead of re-implementing OS primitives. Follow this discipline:

Use the ProcessHost seam for pid lifecycle. For terminate / force-kill / liveness, call get_process_host() rather than guarding os.kill / signal.SIGKILL / taskkill behind your own sys.platform branch:
```
from bmad_loop.process_host import get_process_host

host = get_process_host()
host.terminate(pid)
if host.is_alive(pid):
    host.force_kill(pid)
```
The seam already carries the POSIX and Windows behavior, so the script gains a new OS for free when a host registers.
Stay dependency-free. Beyond bmad_loop itself, import only the stdlib so the script runs anywhere the core does. If you genuinely need a third-party package on one platform, make it an optional extra in pyproject.toml and import it lazily with a clear error if missing — never at module top level. The bundled Unity plugin does exactly this for psutil: imported only on non-Linux process discovery (a core dependency on Windows, the non-linux extra on macOS), so the dep-free Linux/WSL path never pulls it in.
Guard the primitives that have no seam. Anything absent or differently-shaped on Windows that isn't behind a seam — cp/--reflink, symlinks, /proc scanning, /tmp, start_new_session — still needs a fallback behind a sys.platform branch, with a # portability: <reason> comment so the intent (and the CI portability guard, tests/test_portability_guard.py) stays honest. Keep the Linux fast path byte-identical; the Windows branch can be best-effort and is not exercised until a native-Windows backend ships. WSL is Linux, so it takes the fast path unchanged.

The Unity plugin's unity_teardown.py is the worked example: it delegates its SIGTERM→SIGKILL sweep of leaked Editor / MCP-server processes to get_process_host() (so it inherits Windows behavior), while still doing its own worktree-bound process discovery via the guarded /proc-with-psutil-fallback scan. See it alongside unity_setup.py / unity_cleanup.py (and the Game Engine plugin guide) for both shapes.

Reference

Model + base class: src/bmad_loop/plugins/model.py
Manifest parser: src/bmad_loop/plugins/manifest.py
Discovery + overlay + api-check: src/bmad_loop/plugins/loader.py
Trust gate: src/bmad_loop/plugins/trust.py
Registry (the inter-pillar contract): src/bmad_loop/plugins/registry.py
Hook bus + dispatch: src/bmad_loop/plugins/bus.py
Hook context + veto: src/bmad_loop/plugins/context.py
Settings schema: src/bmad_loop/settings_schema.py
The bundled Unity engine plugin (a real, complex example): src/bmad_loop/data/plugins/unity/
Game-engine specifics: Game Engine plugin guide