fix(builders): correct {project-root} path convention rule

The path standards scanner incorrectly enforced that {project-root} was
only valid before /_bmad. The correct semantic is that {project-root} is
valid for ANY project-scope path — the distinction is project-scope vs
skill-internal, not _bmad vs everything else.

Changes across workflow-builder and agent-builder (12 files):

Scanner scripts (scan-path-standards.py):
- Removed PROJECT_ROOT_NOT_BMAD_RE (false-positive on valid paths like
  {project-root}/docs/report.md)
- Added DOUBLE_PREFIX_RE to catch {project-root}/{config-var} where
  config variables already contain {project-root} at runtime
- Updated category from project-root-not-bmad to double-prefix
- Bumped version to 2.1.0

Reference docs (standard-fields.md, quality-dimensions.md):
- Renamed "Project _bmad Paths" to "Project-Scope Paths"
- Added non-_bmad example ({project-root}/docs/report.md)
- Changed rule from "Only use {project-root} for _bmad paths" to
  "Use {project-root} for any project-scope path"

Build process docs (build-process.md):
- Updated path conventions section in both builders

Additional docs:
- convert-process.md: updated change-signal table
- script-opportunities-reference.md: fixed comment in script example
- builder-commands.md: updated scanner description
- skill-authoring-best-practices.md: updated path construction rule

Author: bmadcode

docs/explanation/skill-authoring-best-practices.md

@@ -33,7 +33,7 @@ Six dimensions to keep in mind during the build phase. The quality scanners chec
 | **Intelligence Placement** | Scripts handle plumbing (fetch, transform, validate). Prompts handle judgment (interpret, classify, decide). If a script contains an `if` that decides what content _means_, intelligence has leaked |
 | **Progressive Disclosure** | SKILL.md stays focused; stage instructions go in `prompts/`, reference data in `resources/`                                                                                                          |
 | **Description Format**     | Two parts: `[5-8 word summary]. [Use when user says 'X' or 'Y'.]` — default to conservative triggering                                                                                               |
-| **Path Construction**      | Never use `{skill-root}`. Only use `{project-root}` for `_bmad` paths. Config variables used directly — they already contain `{project-root}`                                                        |
+| **Path Construction**      | Never use `{skill-root}`. Use `{project-root}` for any project-scope path, `./` for skill-internal. Config variables used directly — they already contain `{project-root}`                            |
 | **Token Efficiency**       | Remove genuine waste (repetition, defensive padding). Preserve context that enables judgment (domain framing, rationale)                                                                             |
 
 ## Common Patterns

docs/reference/builder-commands.md

@@ -112,7 +112,7 @@ Before completing the build, both builders run deterministic validation.
 
 | Script                   | What It Checks                                                                            |
 | ------------------------ | ----------------------------------------------------------------------------------------- |
-| `scan-path-standards.py` | Path conventions — no `{skill-root}`, `{project-root}` only for `_bmad`, no double-prefix |
+| `scan-path-standards.py` | Path conventions — no `{skill-root}`, `{project-root}` for project-scope, `./` for skill-internal, no double-prefix |
 | `scan-scripts.py`        | Script portability, PEP 723 metadata, agentic design, unit test presence                  |
 
 Critical issues block completion. Warnings are noted but don't block.

skills/bmad-agent-builder/build-process.md

@@ -68,7 +68,7 @@ Key structural context:
 **Path conventions (CRITICAL):**
 
 - Memory: `{project-root}/_bmad/memory/{skillName}-sidecar/`
-- Project artifacts: `{project-root}/_bmad/...`
+- Project-scope paths: `{project-root}/...` (any path relative to project root)
 - Skill-internal: `./references/`, `./scripts/`
 - Config variables used directly — they already contain full paths (no `{project-root}` prefix)
 

skills/bmad-agent-builder/references/quality-dimensions.md

@@ -45,7 +45,7 @@ Default to conservative triggering. See `./references/standard-fields.md` for fu
 
 ## 6. Path Construction
 
-Only use `{project-root}` for `_bmad` paths. Config variables used directly — they already contain `{project-root}`.
+Use `{project-root}` for any project-scope path. Use `./` for skill-internal paths. Config variables used directly — they already contain `{project-root}`.
 
 See `./references/standard-fields.md` for correct/incorrect patterns.
 

skills/bmad-agent-builder/references/script-opportunities-reference.md

@@ -118,7 +118,7 @@ All scripts use PEP 723 and `--help`. When a skill's prompt needs to invoke a sc
 - ## Read Access section exists
 - ## Write Access section exists
 - ## Deny Zones section exists (can be empty)
-- Paths use placeholders correctly ({project-root} for _bmad paths, relative for skill-internal)
+- Paths use placeholders correctly ({project-root} for project-scope paths, ./ for skill-internal)
 ```
 
 **Output:** Structured JSON of read/write/deny zones

skills/bmad-agent-builder/references/standard-fields.md

@@ -75,6 +75,13 @@ Always use `{project-root}` prefix: `{project-root}/_bmad/memory/{skillName}-sid
 
 The sidecar `index.md` is the single entry point to the agent's memory system — it tells the agent what else to load (boundaries, logs, references, etc.). Load it once on activation; don't duplicate load instructions for individual memory files.
 
+### Project-Scope Paths
+
+Use `{project-root}/...` for any path relative to the project root:
+
+- `{project-root}/_bmad/planning/prd.md`
+- `{project-root}/docs/report.md`
+
 ### Config Variables
 
 Use directly — they already contain `{project-root}` in their resolved values:

skills/bmad-agent-builder/scripts/scan-path-standards.py

@@ -2,9 +2,9 @@
 """Deterministic path standards scanner for BMad skills.
 
 Validates all .md and .json files against BMad path conventions:
-1. {project-root} only valid before /_bmad
+1. {project-root} for any project-scope path (not just _bmad)
 2. Bare _bmad references must have {project-root} prefix
-3. Config variables used directly (no double-prefix)
+3. Config variables used directly — no double-prefix with {project-root}
 4. Skill-internal paths must use ./ prefix (references/, scripts/, assets/)
 5. No ../ parent directory references
 6. No absolute paths
@@ -28,8 +28,8 @@
 
 
 # Patterns to detect
-# {project-root} NOT followed by /_bmad
-PROJECT_ROOT_NOT_BMAD_RE = re.compile(r'\{project-root\}/(?!_bmad)')
+# Double-prefix: {project-root}/{config-variable} — config vars already contain project-root
+DOUBLE_PREFIX_RE = re.compile(r'\{project-root\}/\{[^}]+\}')
 # Bare _bmad without {project-root} prefix — match _bmad at word boundary
 # but not when preceded by {project-root}/
 BARE_BMAD_RE = re.compile(r'(?<!\{project-root\}/)_bmad[/\s]')
@@ -142,8 +142,8 @@ def scan_file(filepath: Path, skip_fenced: bool = True) -> list[dict]:
     rel_path = filepath.name
 
     checks = [
-        (PROJECT_ROOT_NOT_BMAD_RE, 'project-root-not-bmad', 'critical',
-         '{project-root} used for non-_bmad path — only valid use is {project-root}/_bmad/...'),
+        (DOUBLE_PREFIX_RE, 'double-prefix', 'critical',
+         'Double-prefix: {project-root}/{variable} — config variables already contain {project-root} at runtime'),
         (ABSOLUTE_PATH_RE, 'absolute-path', 'high',
          'Absolute path found — not portable across machines'),
         (HOME_PATH_RE, 'absolute-path', 'high',
@@ -259,9 +259,8 @@ def scan_skill(skill_path: Path, skip_fenced: bool = True) -> dict:
     # Build summary
     by_severity = {'critical': 0, 'high': 0, 'medium': 0, 'low': 0}
     by_category = {
-        'project_root_not_bmad': 0,
-        'bare_bmad': 0,
         'double_prefix': 0,
+        'bare_bmad': 0,
         'absolute_path': 0,
         'relative_prefix': 0,
         'bare_internal_path': 0,
@@ -281,7 +280,7 @@ def scan_skill(skill_path: Path, skip_fenced: bool = True) -> dict:
     return {
         'scanner': 'path-standards',
         'script': 'scan-path-standards.py',
-        'version': '2.0.0',
+        'version': '2.1.0',
         'skill_path': str(skill_path),
         'timestamp': datetime.now(timezone.utc).isoformat(),
         'files_scanned': files_scanned,

skills/bmad-workflow-builder/build-process.md

@@ -93,7 +93,7 @@ Confirm with user: phase-name, after (dependencies), before (downstream), is-req
 **Path conventions (CRITICAL):**
 
 - Skill-internal: `./references/`, `./scripts/`
-- Project `_bmad` paths: `{project-root}/_bmad/...`
+- Project-scope paths: `{project-root}/...` (any path relative to project root)
 - Config variables used directly — they already contain `{project-root}`
 
 ## Phase 4: Draft & Refine

skills/bmad-workflow-builder/references/convert-process.md

@@ -84,7 +84,7 @@ Not every conversion is about bloat — some skills are well-intentioned but non
 | **Progressive Disclosure** | Monolithic content split into SKILL.md routing + references |
 | **Outcome-Driven Rewrite** | Prescriptive instructions reframed as outcomes |
 | **Frontmatter/Description** | Added or fixed BMad-compliant frontmatter and trigger phrases |
-| **Path Convention Fixes** | Corrected file references to use `./references/`, `{project-root}/_bmad/`, etc. |
+| **Path Convention Fixes** | Corrected file references to use `./` for skill-internal, `{project-root}/` for project-scope |
 
 Severity: **high** = significant impact on quality or compliance, **medium** = notable improvement, **low** = minor or stylistic.
 

skills/bmad-workflow-builder/references/quality-dimensions.md

@@ -44,7 +44,7 @@ Default to conservative triggering. See `./references/standard-fields.md` for fu
 
 ## 6. Path Construction
 
-Only use `{project-root}` for `_bmad` paths. Config variables used directly — they already contain `{project-root}`.
+Use `{project-root}` for any project-scope path. Use `./` for skill-internal paths. Config variables used directly — they already contain `{project-root}`.
 
 See `./references/standard-fields.md` for correct/incorrect patterns.