From 4fdf0c5af2c06da08e1b16172750d95d9f689830 Mon Sep 17 00:00:00 2001 From: Alex Verkhovsky Date: Tue, 6 Oct 2026 06:55:50 -0700 Subject: [PATCH 1/4] refactor(code-review): cut the boilerplate from workflow.md --- skills/bmad-code-review/workflow.md | 58 ++++++----------------------- 1 file changed, 12 insertions(+), 46 deletions(-) diff --git a/skills/bmad-code-review/workflow.md b/skills/bmad-code-review/workflow.md index d58fbfd946..b79536906b 100644 --- a/skills/bmad-code-review/workflow.md +++ b/skills/bmad-code-review/workflow.md @@ -4,66 +4,32 @@ # Code Review Workflow -**Goal:** Review code changes adversarially. No noise, no filler. +Several independent reviewers hunt for defects in a code change; this workflow sends them the change, then verifies, triages, presents, and fixes what they found. -**CRITICAL:** If a step directs you to another snapshot file, read it fully and follow it. No exceptions. - -Subagents, when the capability is available, are an important part of this workflow. Use them as directed by the workflow steps. -If you need an explicit user instruction to run them, ask once now for the whole workflow run. +Subagents are an important part of this workflow. Use them wherever a step calls for them, if you can. If you need the user's permission to run them, ask once now for the whole run. ## Conventions -- Every operational cross-file reference in this workflow is an absolute snapshot path. Open it directly; do not resolve it relative to a skill directory. -- `{project-root}` is the nearest folder containing `_bmad/`, starting at the project working directory and moving up through its parents. +- Every cross-file reference in this workflow is an absolute path. Open it directly; do not resolve it relative to a skill directory. +- `{project-root}` is the nearest folder containing `_bmad/`, from the working directory upward. - `{date}` is the current system datetime. +- When a step directs you to another file, read it fully and follow it. Load one step at a time, when it is reached. +- A step that shows a menu or checkpoint halts there and waits for the user. -## On Activation - -### Step 1: Execute Prepend Steps +## On activation -Execute each of these steps in order before proceeding (`_None._` means skip): +Run each of these in order before step 1 (`_None._` means skip): {{ workflow.activation_steps_prepend }} -### Step 2: Load Persistent Facts - -Treat every entry below as foundational context you carry for the rest of the workflow run. Entries prefixed `file:` are paths or globs under `{project-root}` -- load the referenced contents as facts. All other entries are facts verbatim (`_None._` means none): +Hold every entry below as fact for the whole run. Entries prefixed `file:` are paths or globs under `{project-root}` to read; the rest are facts verbatim (`_None._` means none): {{ workflow.persistent_facts }} -### Step 3: Execute Append Steps - -Execute each of these steps in order (`_None._` means skip): +Then run each of these in order (`_None._` means skip): {{ workflow.activation_steps_append }} -Activation is complete after all activation steps have run. - -## WORKFLOW ARCHITECTURE - -This uses **step-file architecture** for disciplined execution: - -- **Micro-file Design**: Each step is self-contained and followed exactly -- **Just-In-Time Loading**: Only load the current step file -- **Sequential Enforcement**: Complete steps in order, no skipping -- **State Tracking**: Persist progress via in-memory variables -- **Append-Only Building**: Build artifacts incrementally - -### Step Processing Rules - -1. **READ COMPLETELY**: Read the entire step file before acting -2. **FOLLOW SEQUENCE**: Execute sections in order -3. **WAIT FOR INPUT**: Halt at checkpoints and wait for human -4. **LOAD NEXT**: When directed, read fully and follow the next step file - -### Critical Rules (NO EXCEPTIONS) - -- **NEVER** load multiple step files simultaneously -- **ALWAYS** read entire step file before execution -- **NEVER** skip steps or optimize the sequence -- **ALWAYS** follow the exact instructions in the step file -- **ALWAYS** halt at checkpoints and wait for human input - -## FIRST STEP +## First step -Read fully and follow: `{{ rendered("step-01-gather-context.md") }}` to begin the workflow. +Read fully and follow `{{ rendered("step-01-gather-context.md") }}`. From f133848b3c8810ddfe7a9cc95da1c6be7923be46 Mon Sep 17 00:00:00 2001 From: Alex Verkhovsky Date: Tue, 6 Oct 2026 07:19:07 -0700 Subject: [PATCH 2/4] docs(skills): define {project-root} in SKILL.md, where it is first resolved --- skills/bmad-build-auto/SKILL.md | 5 ++++- skills/bmad-build-auto/workflow.md | 1 - skills/bmad-build/SKILL.md | 5 ++++- skills/bmad-build/workflow.md | 1 - skills/bmad-code-review/SKILL.md | 3 ++- skills/bmad-code-review/workflow.md | 1 - skills/bmad-retrospective/SKILL.md | 5 ++++- skills/bmad-retrospective/workflow.md | 1 - .../shapes/rendered-skill/assets/SKILL-template.md | 5 ++++- .../bmad-toolsmith/shapes/rendered-skill/assets/workflow.md | 1 - 10 files changed, 18 insertions(+), 10 deletions(-) diff --git a/skills/bmad-build-auto/SKILL.md b/skills/bmad-build-auto/SKILL.md index 25413f0593..f366960a01 100644 --- a/skills/bmad-build-auto/SKILL.md +++ b/skills/bmad-build-auto/SKILL.md @@ -3,7 +3,10 @@ name: bmad-build-auto description: 'One iteration of an unattended development loop. Use when invoked by name' --- -Run the following command exactly once without changing the current working directory. Replace `{project-root}` with the absolute path to the project root and `{skill-root}` with the absolute path to this skill's directory: +Run the following command exactly once without changing the current working directory. + +Replace `{project-root}` with the nearest folder containing `_bmad/`, from the working directory upward. +Replace `{skill-root}` with the absolute path to this skill's directory. ```bash uv run --no-cache "{project-root}/_bmad/scripts/render_skill.py" --project-root "{project-root}" --skill "{skill-root}" diff --git a/skills/bmad-build-auto/workflow.md b/skills/bmad-build-auto/workflow.md index 1f065a42de..f8dbf25bb2 100644 --- a/skills/bmad-build-auto/workflow.md +++ b/skills/bmad-build-auto/workflow.md @@ -55,7 +55,6 @@ A full plan is "Ready for Development" when: ## Conventions - Every operational cross-file reference in this workflow is an absolute snapshot path. Open it directly; do not resolve it relative to a skill directory. -- `{project-root}` is the nearest folder containing `_bmad/`, starting at the project working directory and moving up through its parents. - Whenever this workflow captures or records a version-control revision, obtain the full canonical identifier directly from version control and preserve it verbatim. ## On Activation diff --git a/skills/bmad-build/SKILL.md b/skills/bmad-build/SKILL.md index a87006b495..a9067933f6 100644 --- a/skills/bmad-build/SKILL.md +++ b/skills/bmad-build/SKILL.md @@ -3,7 +3,10 @@ name: bmad-build description: 'Turns implementation work into working code, reviewed and verified. Use when the user delegates a feature, story, bug fix, or meaningful change; a bare story or issue link counts. Skip obvious, low-risk mechanical maintenance such as small ignore-file, typo-only, formatting-only, or configuration-hygiene edits. Explicit BMAD requests always qualify. Do not volunteer for user-directed interactive edits or version-control operations that only record existing work.' --- -Run the following command exactly once without changing the current working directory. Replace `{project-root}` with the absolute path to the project root and `{skill-root}` with the absolute path to this skill's directory: +Run the following command exactly once without changing the current working directory. + +Replace `{project-root}` with the nearest folder containing `_bmad/`, from the working directory upward. +Replace `{skill-root}` with the absolute path to this skill's directory. ```bash uv run --no-cache "{project-root}/_bmad/scripts/render_skill.py" --project-root "{project-root}" --skill "{skill-root}" diff --git a/skills/bmad-build/workflow.md b/skills/bmad-build/workflow.md index c9e8099560..244d8e09e0 100644 --- a/skills/bmad-build/workflow.md +++ b/skills/bmad-build/workflow.md @@ -33,7 +33,6 @@ A plan should target a **single user-facing goal** within **900–1600 tokens**: ## Conventions - Every operational cross-file reference in this workflow is an absolute snapshot path. Open it directly; do not resolve it relative to a skill directory. -- `{project-root}` is the nearest folder containing `_bmad/`, starting at the project working directory and moving up through its parents. - Whenever this workflow captures or records a version-control revision, obtain the full canonical identifier directly from version control and preserve it verbatim. ## On Activation diff --git a/skills/bmad-code-review/SKILL.md b/skills/bmad-code-review/SKILL.md index 922bbf6bc2..fc35e7c1e8 100644 --- a/skills/bmad-code-review/SKILL.md +++ b/skills/bmad-code-review/SKILL.md @@ -5,7 +5,8 @@ description: 'Review code changes with several independent reviewers in parallel Run the following command exactly once without changing the current working directory. -Replace `{project-root}` with the absolute path to the project root and `{skill-root}` with the absolute path to this skill's directory. +Replace `{project-root}` with the nearest folder containing `_bmad/`, from the working directory upward. +Replace `{skill-root}` with the absolute path to this skill's directory. If the invocation specifies a `quick` or `thorough` review, append `--set workflow.review=` to the command. diff --git a/skills/bmad-code-review/workflow.md b/skills/bmad-code-review/workflow.md index b79536906b..6d43b8630d 100644 --- a/skills/bmad-code-review/workflow.md +++ b/skills/bmad-code-review/workflow.md @@ -11,7 +11,6 @@ Subagents are an important part of this workflow. Use them wherever a step calls ## Conventions - Every cross-file reference in this workflow is an absolute path. Open it directly; do not resolve it relative to a skill directory. -- `{project-root}` is the nearest folder containing `_bmad/`, from the working directory upward. - `{date}` is the current system datetime. - When a step directs you to another file, read it fully and follow it. Load one step at a time, when it is reached. - A step that shows a menu or checkpoint halts there and waits for the user. diff --git a/skills/bmad-retrospective/SKILL.md b/skills/bmad-retrospective/SKILL.md index 4dbf09daee..dd410bbbe2 100644 --- a/skills/bmad-retrospective/SKILL.md +++ b/skills/bmad-retrospective/SKILL.md @@ -3,7 +3,10 @@ name: bmad-retrospective description: 'Review a finished epic folder in the ticket tree against the evidence it left behind — the epic file, each ticket plan, diffs, commits — and produce a retrospective with sourced findings, action items, and an acceptance decision. Use when the user says "run a retrospective" or "lets retro the epic [epic]". Supports -H/--headless' --- -Run the following command exactly once without changing the current working directory. Replace `{project-root}` with the absolute path to the project root and `{skill-root}` with the absolute path to this skill's directory: +Run the following command exactly once without changing the current working directory. + +Replace `{project-root}` with the nearest folder containing `_bmad/`, from the working directory upward. +Replace `{skill-root}` with the absolute path to this skill's directory. ```bash uv run --no-cache "{project-root}/_bmad/scripts/render_skill.py" --project-root "{project-root}" --skill "{skill-root}" diff --git a/skills/bmad-retrospective/workflow.md b/skills/bmad-retrospective/workflow.md index ef02221f61..27845ab2ae 100644 --- a/skills/bmad-retrospective/workflow.md +++ b/skills/bmad-retrospective/workflow.md @@ -9,7 +9,6 @@ Every finding you report carries a source reference (file, line, commit, or log) ## Conventions - Every operational cross-file reference in this workflow is an absolute snapshot path. Open it directly; do not resolve it relative to a skill directory. -- `{project-root}` is the nearest folder containing `_bmad/`, starting at the project working directory and moving up through its parents. - `{date}` is the current system datetime. Never state time estimates — AI has changed development speed, so hour/day/week predictions are noise. ## Modes diff --git a/skills/bmad-toolsmith/shapes/rendered-skill/assets/SKILL-template.md b/skills/bmad-toolsmith/shapes/rendered-skill/assets/SKILL-template.md index 48ac7115b4..7589bab88f 100644 --- a/skills/bmad-toolsmith/shapes/rendered-skill/assets/SKILL-template.md +++ b/skills/bmad-toolsmith/shapes/rendered-skill/assets/SKILL-template.md @@ -2,7 +2,10 @@ name: {name} description: '{description}' --- -Run the following command exactly once without changing the current working directory. Replace `{project-root}` with the absolute path to the project root and `{skill-root}` with the absolute path to this skill's directory: +Run the following command exactly once without changing the current working directory. + +Replace `{project-root}` with the nearest folder containing `_bmad/`, from the working directory upward. +Replace `{skill-root}` with the absolute path to this skill's directory. ```bash uv run --no-cache "{project-root}/_bmad/scripts/render_skill.py" --project-root "{project-root}" --skill "{skill-root}" diff --git a/skills/bmad-toolsmith/shapes/rendered-skill/assets/workflow.md b/skills/bmad-toolsmith/shapes/rendered-skill/assets/workflow.md index 98132b8a3c..590b408890 100644 --- a/skills/bmad-toolsmith/shapes/rendered-skill/assets/workflow.md +++ b/skills/bmad-toolsmith/shapes/rendered-skill/assets/workflow.md @@ -6,7 +6,6 @@ ## Conventions - Every cross-file reference in this workflow is an absolute snapshot path. Open it directly; do not resolve it relative to a skill directory. -- `{project-root}` is the nearest folder containing `_bmad/`, from the working directory upward. - When a step directs you to another file, read it fully and follow it. Load one step at a time, when it is reached. - A step that shows a menu halts there and waits for the user. From 259d4f32e98ffc237cc9add7a885ef9bba4669ac Mon Sep 17 00:00:00 2001 From: Alex Verkhovsky Date: Tue, 6 Oct 2026 07:26:52 -0700 Subject: [PATCH 3/4] docs(skills): drop the {date} definition its uses make obvious --- skills/bmad-build-auto/step-04-review.md | 2 +- skills/bmad-code-review/workflow.md | 1 - skills/bmad-retrospective/workflow.md | 2 +- 3 files changed, 2 insertions(+), 3 deletions(-) diff --git a/skills/bmad-build-auto/step-04-review.md b/skills/bmad-build-auto/step-04-review.md index 2528afb728..59728a435a 100644 --- a/skills/bmad-build-auto/step-04-review.md +++ b/skills/bmad-build-auto/step-04-review.md @@ -101,7 +101,7 @@ Write `lenses_ran` — the ids launched, in launch order — to `{plan_file}` fr - findings: - `[verdict]` `[intent_gap|bad_plan|patch|defer|reject]` — ``` - Where `{date}` is the current system date. One row per finding from every lens, in the order the lenses reported them; `` must equal the number of findings the lenses reported — a finding missing from the log is a triage failure. Members of a grouped entry keep their own rows and share the route. + One row per finding from every lens, in the order the lenses reported them; `` must equal the number of findings the lenses reported — a finding missing from the log is a triage failure. Members of a grouped entry keep their own rows and share the route. 5. Process entries in cascading order. If intent_gap exists, lower entries are moot; follow the intent_gap branch below. If bad_plan exists, lower entries are moot since code will be re-derived. If neither exists, process patch and defer normally. Before each bad_plan loopback, read `{plan_file}` frontmatter `review_loop_iteration` (missing means `0`), increment it by 1, and write it back. If it exceeds 5, append the triage-log entry for this pass, then HALT with status `blocked` and blocking condition `review repair loop exceeded 5 iterations (non-convergence)`. - **intent_gap** — Root cause is inside ``. Save the attempted change as a patch file beside `{plan_file}`, named after it with `.patch` for `.md`, and reference it from the triage-log entry, then revert code changes. Append the triage-log entry for this pass, then HALT with status `blocked`, blocking condition `intent gap`, and include the unresolved questions and the saved patch path. - **bad_plan** — Root cause is outside ``. Do not modify content inside ``. Before reverting code: extract KEEP instructions for positive preservation (what worked well and must survive re-derivation). Revert code changes. Read the `## Plan Change Log` in `{plan_file}` and strictly respect all logged constraints when amending the sections outside `` that contain the root cause. Append a new change-log entry recording: the triggering finding, what was amended, the known-bad state avoided, and the KEEP instructions. Append the triage-log entry for this pass, recording in each bad_plan row the amendment it triggered. Read fully and follow `{{ rendered("step-03-implement.md") }}` to re-derive the code, then this step will run again. diff --git a/skills/bmad-code-review/workflow.md b/skills/bmad-code-review/workflow.md index 6d43b8630d..0e5c609844 100644 --- a/skills/bmad-code-review/workflow.md +++ b/skills/bmad-code-review/workflow.md @@ -11,7 +11,6 @@ Subagents are an important part of this workflow. Use them wherever a step calls ## Conventions - Every cross-file reference in this workflow is an absolute path. Open it directly; do not resolve it relative to a skill directory. -- `{date}` is the current system datetime. - When a step directs you to another file, read it fully and follow it. Load one step at a time, when it is reached. - A step that shows a menu or checkpoint halts there and waits for the user. diff --git a/skills/bmad-retrospective/workflow.md b/skills/bmad-retrospective/workflow.md index 27845ab2ae..a2f4bfcfaf 100644 --- a/skills/bmad-retrospective/workflow.md +++ b/skills/bmad-retrospective/workflow.md @@ -9,7 +9,7 @@ Every finding you report carries a source reference (file, line, commit, or log) ## Conventions - Every operational cross-file reference in this workflow is an absolute snapshot path. Open it directly; do not resolve it relative to a skill directory. -- `{date}` is the current system datetime. Never state time estimates — AI has changed development speed, so hour/day/week predictions are noise. +- Never state time estimates — AI has changed development speed, so hour/day/week predictions are noise. ## Modes From 34e0367c66e5e5c851977d6f07520151223923a2 Mon Sep 17 00:00:00 2001 From: Alex Verkhovsky Date: Tue, 6 Oct 2026 07:45:31 -0700 Subject: [PATCH 4/4] docs(skills): drop the absolute-path convention the rendered links make visible --- skills/bmad-build-auto/workflow.md | 1 - skills/bmad-build/workflow.md | 1 - skills/bmad-code-review/workflow.md | 1 - skills/bmad-retrospective/workflow.md | 1 - skills/bmad-toolsmith/shapes/rendered-skill/assets/workflow.md | 1 - 5 files changed, 5 deletions(-) diff --git a/skills/bmad-build-auto/workflow.md b/skills/bmad-build-auto/workflow.md index f8dbf25bb2..17ecf7b5bd 100644 --- a/skills/bmad-build-auto/workflow.md +++ b/skills/bmad-build-auto/workflow.md @@ -54,7 +54,6 @@ A full plan is "Ready for Development" when: ## Conventions -- Every operational cross-file reference in this workflow is an absolute snapshot path. Open it directly; do not resolve it relative to a skill directory. - Whenever this workflow captures or records a version-control revision, obtain the full canonical identifier directly from version control and preserve it verbatim. ## On Activation diff --git a/skills/bmad-build/workflow.md b/skills/bmad-build/workflow.md index 244d8e09e0..485332be7b 100644 --- a/skills/bmad-build/workflow.md +++ b/skills/bmad-build/workflow.md @@ -32,7 +32,6 @@ A plan should target a **single user-facing goal** within **900–1600 tokens**: ## Conventions -- Every operational cross-file reference in this workflow is an absolute snapshot path. Open it directly; do not resolve it relative to a skill directory. - Whenever this workflow captures or records a version-control revision, obtain the full canonical identifier directly from version control and preserve it verbatim. ## On Activation diff --git a/skills/bmad-code-review/workflow.md b/skills/bmad-code-review/workflow.md index 0e5c609844..fc80304acb 100644 --- a/skills/bmad-code-review/workflow.md +++ b/skills/bmad-code-review/workflow.md @@ -10,7 +10,6 @@ Subagents are an important part of this workflow. Use them wherever a step calls ## Conventions -- Every cross-file reference in this workflow is an absolute path. Open it directly; do not resolve it relative to a skill directory. - When a step directs you to another file, read it fully and follow it. Load one step at a time, when it is reached. - A step that shows a menu or checkpoint halts there and waits for the user. diff --git a/skills/bmad-retrospective/workflow.md b/skills/bmad-retrospective/workflow.md index a2f4bfcfaf..c8fe13937d 100644 --- a/skills/bmad-retrospective/workflow.md +++ b/skills/bmad-retrospective/workflow.md @@ -8,7 +8,6 @@ Every finding you report carries a source reference (file, line, commit, or log) ## Conventions -- Every operational cross-file reference in this workflow is an absolute snapshot path. Open it directly; do not resolve it relative to a skill directory. - Never state time estimates — AI has changed development speed, so hour/day/week predictions are noise. ## Modes diff --git a/skills/bmad-toolsmith/shapes/rendered-skill/assets/workflow.md b/skills/bmad-toolsmith/shapes/rendered-skill/assets/workflow.md index 590b408890..5b9a0b5b7f 100644 --- a/skills/bmad-toolsmith/shapes/rendered-skill/assets/workflow.md +++ b/skills/bmad-toolsmith/shapes/rendered-skill/assets/workflow.md @@ -5,7 +5,6 @@ ## Conventions -- Every cross-file reference in this workflow is an absolute snapshot path. Open it directly; do not resolve it relative to a skill directory. - When a step directs you to another file, read it fully and follow it. Load one step at a time, when it is reached. - A step that shows a menu halts there and waits for the user.