refactor(skills): cut boilerplate and dead conventions from rendered workflows

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}"

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]` <finding summary> — <evidence: the refutation for false, what would settle it for maybe-false, the action taken for patches, why a rejected low was not worth fixing>
    ```
-   Where `{date}` is the current system date. One row per finding from every lens, in the order the lenses reported them; `<total>` 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; `<total>` 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 `<intent-contract>`. 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 `<intent-contract>`. Do not modify content inside `<intent-contract>`. 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 `<intent-contract>` 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.

skills/bmad-build-auto/workflow.md

@@ -54,8 +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.
-- `{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

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}"

skills/bmad-build/workflow.md

@@ -32,8 +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.
-- `{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

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=<value>` to the command.
 

skills/bmad-code-review/workflow.md

@@ -4,66 +4,29 @@
 
 # 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.
-- `{date}` is the current system datetime.
-
-## On Activation
+- 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.
 
-### 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") }}`.

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}"

skills/bmad-retrospective/workflow.md

@@ -8,9 +8,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.
-- `{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.
+- Never state time estimates — AI has changed development speed, so hour/day/week predictions are noise.
 
 ## Modes
 

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}"

skills/bmad-toolsmith/shapes/rendered-skill/assets/workflow.md

@@ -5,8 +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.
-- `{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.