feat: add reminders page, BMad skills upgrade, MCP server refactor

- Add reminders page with navigation support
- Upgrade BMad builder module to skills-based architecture
- Refactor MCP server: extract tools and auth into separate modules
- Add connections cache, custom AI provider support
- Update prisma schema and generated client
- Various UI/UX improvements and i18n updates
- Add service worker for PWA support

Made-with: Cursor

_bmad/bmb/bmad-workflow-builder/references/classification-reference.md

@@ -0,0 +1,59 @@
+# Workflow Classification Reference
+
+Classify the skill type based on user requirements. This table is for internal use — DO NOT show to user.
+
+## 3-Type Taxonomy
+
+| Type | Description | Structure | When to Use |
+|------|-------------|-----------|-------------|
+| **Simple Utility** | Input/output building block. Headless, composable, often has scripts. | Single SKILL.md + scripts/ | Composable building block with clear input/output, single-purpose |
+| **Simple Workflow** | Multi-step process contained in a single SKILL.md. Minimal or no prompt files. | SKILL.md + optional references/ | Multi-step process that fits in one file, no progressive disclosure needed |
+| **Complex Workflow** | Multi-stage with progressive disclosure, numbered prompt files at root, config integration. May support headless mode. | SKILL.md (routing) + prompt stages at root + references/ | Multiple stages, long-running process, progressive disclosure, routing logic |
+
+## Decision Tree
+
+```
+1. Is it a composable building block with clear input/output?
+   └─ YES → Simple Utility
+   └─ NO ↓
+
+2. Can it fit in a single SKILL.md without progressive disclosure?
+   └─ YES → Simple Workflow
+   └─ NO ↓
+
+3. Does it need multiple stages, long-running process, or progressive disclosure?
+   └─ YES → Complex Workflow
+```
+
+## Classification Signals
+
+### Simple Utility Signals
+- Clear input → processing → output pattern
+- No user interaction needed during execution
+- Other skills/workflows call it
+- Deterministic or near-deterministic behavior
+- Could be a script but needs LLM judgment
+- Examples: JSON validator, schema checker, format converter
+
+### Simple Workflow Signals
+- 3-8 numbered steps
+- User interaction at specific points
+- Uses standard tools (gh, git, npm, etc.)
+- Produces a single output artifact
+- No need to track state across compactions
+- Examples: PR creator, deployment checklist, code review
+
+### Complex Workflow Signals
+- Multiple distinct phases/stages
+- Long-running (likely to hit context compaction)
+- Progressive disclosure needed (too much for one file)
+- Routing logic in SKILL.md dispatches to stage prompts
+- Produces multiple artifacts across stages
+- May support headless/autonomous mode
+- Examples: agent builder, module builder, project scaffolder
+
+## Module Context (Orthogonal)
+
+Module context is asked for ALL types:
+- **Module-based:** Part of a BMad module. Uses `bmad-{modulecode}-{skillname}` naming. Config loading includes a fallback pattern — if config is missing, the skill informs the user that the module setup skill is available and continues with sensible defaults.
+- **Standalone:** Independent skill. Uses `bmad-{skillname}` naming. Config loading is best-effort — load if available, use defaults if not, no mention of a setup skill.

_bmad/bmb/bmad-workflow-builder/references/complex-workflow-patterns.md

@@ -0,0 +1,119 @@
+# BMad Module Workflows
+
+Advanced patterns for BMad module workflows — long-running, multi-stage processes with progressive disclosure, config integration, and compaction survival.
+
+---
+
+## Workflow Persona
+
+BMad workflows treat the human operator as the expert. The agent facilitates — asks clarifying questions, presents options with trade-offs, validates before irreversible actions. The operator knows their domain; the workflow knows the process.
+
+---
+
+## Config Reading and Integration
+
+Workflows read config from `{project-root}/_bmad/config.yaml` and `config.user.yaml`.
+
+### Config Loading Pattern
+
+**Module-based skills** — load with fallback and setup skill awareness:
+```
+Load config from {project-root}/_bmad/config.yaml ({module-code} section) and config.user.yaml.
+If missing: inform user that {module-setup-skill} is available, continue with sensible defaults.
+```
+
+**Standalone skills** — load best-effort:
+```
+Load config from {project-root}/_bmad/config.yaml and config.user.yaml if available.
+If missing: continue with defaults — no mention of setup skill.
+```
+
+### Required Core Variables
+
+Load core config (user preferences, language, output locations) with sensible defaults. If the workflow creates documents, include document output language.
+
+**Example config line for a document-producing workflow:**
+```
+vars: user_name:BMad,communication_language:English,document_output_language:English,output_folder:{project-root}/_bmad-output,bmad_builder_output_folder:{project-root}/bmad-builder-creations/
+```
+
+Config variables used directly in prompts — they already contain `{project-root}` in resolved values.
+
+---
+
+## Long-Running Workflows: Compaction Survival
+
+Workflows that run long may trigger context compaction. Critical state MUST survive in output files.
+
+### The Document-Itself Pattern
+
+**The output document is the cache.** Write directly to the file you're creating, updating progressively. The document stores both content and context:
+
+- **YAML front matter** — paths to input files, current status
+- **Draft sections** — progressive content as it's built
+- **Status marker** — which stage is complete
+
+Each stage after the first reads the output document to recover context. If compacted, re-read input files listed in the YAML front matter.
+
+```markdown
+---
+title: "Analysis: Research Topic"
+status: "analysis"
+inputs:
+  - "{project_root}/docs/brief.md"
+created: "2025-03-02T10:00:00Z"
+updated: "2025-03-02T11:30:00Z"
+---
+```
+
+**When to use:** Guided flows with long documents, yolo flows with multiple turns. Single-pass yolo can wait to write final output.
+
+**When NOT to use:** Short single-turn outputs, purely conversational workflows, multiple independent artifacts (each gets its own file).
+
+---
+
+## Sequential Progressive Disclosure
+
+Use numbered prompt files at the skill root when:
+- Multi-phase workflow with ordered stages
+- Input of one phase affects the next
+- Workflow is long-running and stages shouldn't be visible upfront
+
+### Structure
+
+```
+my-workflow/
+├── SKILL.md                    # Routing + entry logic (minimal)
+├── references/
+│   ├── 01-discovery.md         # Stage 1
+│   ├── 02-planning.md          # Stage 2
+│   ├── 03-execution.md         # Stage 3
+│   └── templates.md            # Supporting reference
+└── scripts/
+    └── validator.sh
+```
+
+Each stage prompt specifies prerequisites, progression conditions, and next destination. SKILL.md is minimal routing logic.
+
+**Keep inline in SKILL.md when:** Simple skill, well-known domain, single-purpose utility, all stages independent.
+
+---
+
+## Module Metadata Reference
+
+BMad module workflows require extended frontmatter metadata. See `./references/metadata-reference.md` for the metadata template and field explanations.
+
+---
+
+## Workflow Architecture Checklist
+
+Before finalizing a BMad module workflow, verify:
+
+- [ ] Facilitator persona — treats operator as expert?
+- [ ] Config integration — language, output locations read and used?
+- [ ] Portable paths — artifacts use `{project_root}`?
+- [ ] Compaction survival — each stage writes to output document?
+- [ ] Document-as-cache — YAML front matter with status and inputs?
+- [ ] Progressive disclosure — stages in `./references/` with progression conditions?
+- [ ] Final polish — subagent polish step at the end?
+- [ ] Recovery — can resume by reading output doc front matter?

_bmad/bmb/bmad-workflow-builder/references/quality-dimensions.md

@@ -0,0 +1,53 @@
+# Quality Dimensions — Quick Reference
+
+Seven dimensions to keep in mind when building skills. The quality scanners check these automatically during quality analysis — this is a mental checklist for the build phase.
+
+## 1. Outcome-Driven Design
+
+Describe what to achieve, not how to get there step by step. Only add procedural detail when the LLM would genuinely fail without it.
+
+- **The test:** Would removing this instruction cause the LLM to produce a worse outcome? If the LLM would do it anyway, the instruction is noise.
+- **Pruning:** If a block teaches the LLM something it already knows — scoring algorithms for subjective judgment, calibration tables for reading the room, weighted formulas for picking relevant participants — cut it. These are things LLMs do naturally.
+- **When procedure IS value:** Exact script invocations, specific file paths, API calls with precise parameters, security-critical operations. These need low freedom because there's one right way.
+
+## 2. Informed Autonomy
+
+The executing agent needs enough context to make judgment calls when situations don't match the script. The Overview establishes this: domain framing, theory of mind, design rationale.
+
+- Simple utilities need minimal context — input/output is self-explanatory
+- Interactive/complex workflows need domain understanding, user perspective, and rationale for non-obvious choices
+- When in doubt, explain *why* — an agent that understands the mission improvises better than one following blind steps
+
+## 3. Intelligence Placement
+
+Scripts handle plumbing (fetch, transform, validate). Prompts handle judgment (interpret, classify, decide).
+
+**Test:** If a script contains an `if` that decides what content *means*, intelligence has leaked.
+
+**Reverse test:** If a prompt validates structure, counts items, parses known formats, compares against schemas, or checks file existence — determinism has leaked into the LLM. That work belongs in a script.
+
+## 4. Progressive Disclosure
+
+SKILL.md stays focused. Detail goes where it belongs.
+
+- Stage instructions → `./references/`
+- Reference data, schemas, large tables → `./references/`
+- Templates, config files → `./assets/`
+- Multi-branch SKILL.md under ~250 lines: fine as-is
+- Single-purpose up to ~500 lines (~5000 tokens): acceptable if focused
+
+## 5. Description Format
+
+Two parts: `[5-8 word summary]. [Use when user says 'X' or 'Y'.]`
+
+Default to conservative triggering. See `./references/standard-fields.md` for full format.
+
+## 6. Path Construction
+
+Only use `{project-root}` for `_bmad` paths. Config variables used directly — they already contain `{project-root}`.
+
+See `./references/standard-fields.md` for correct/incorrect patterns.
+
+## 7. Token Efficiency
+
+Remove genuine waste (repetition, defensive padding, meta-explanation). Preserve context that enables judgment (domain framing, theory of mind, design rationale). These are different things — never trade effectiveness for efficiency. A skill that works correctly but uses extra tokens is always better than one that's lean but fails edge cases.

_bmad/bmb/bmad-workflow-builder/references/script-opportunities-reference.md

@@ -0,0 +1,97 @@
+# Script Opportunities Reference — Workflow Builder
+
+## Core Principle
+
+Scripts handle deterministic operations (validate, transform, count). Prompts handle judgment (interpret, classify, decide). If a check has clear pass/fail criteria, it belongs in a script.
+
+---
+
+## How to Spot Script Opportunities
+
+### The Determinism Test
+
+1. **Given identical input, will it always produce identical output?** → Script candidate.
+2. **Could you write a unit test with expected output?** → Definitely a script.
+3. **Requires interpreting meaning, tone, or context?** → Keep as prompt.
+
+### The Judgment Boundary
+
+| Scripts Handle | Prompts Handle |
+|----------------|----------------|
+| Fetch, Transform, Validate | Interpret, Classify (ambiguous) |
+| Count, Parse, Compare | Create, Decide (incomplete info) |
+| Extract, Format, Check structure | Evaluate quality, Synthesize meaning |
+
+### Signal Verbs in Prompts
+
+When you see these in a workflow's requirements, think scripts first: "validate", "count", "extract", "convert/transform", "compare", "scan for", "check structure", "against schema", "graph/map dependencies", "list all", "detect pattern", "diff/changes between"
+
+### Script Opportunity Categories
+
+| Category | What It Does | Example |
+|----------|-------------|---------|
+| Validation | Check structure, format, schema, naming | Validate frontmatter fields exist |
+| Data Extraction | Pull structured data without interpreting meaning | Extract all `{variable}` references from markdown |
+| Transformation | Convert between known formats | Markdown table to JSON |
+| Metrics | Count, tally, aggregate statistics | Token count per file |
+| Comparison | Diff, cross-reference, verify consistency | Cross-ref prompt names against SKILL.md references |
+| Structure Checks | Verify directory layout, file existence | Skill folder has required files |
+| Dependency Analysis | Trace references, imports, relationships | Build skill dependency graph |
+| Pre-Processing | Extract compact data from large files BEFORE LLM reads them | Pre-extract file metrics into JSON for LLM scanner |
+| Post-Processing | Verify LLM output meets structural requirements | Validate generated YAML parses correctly |
+
+### Your Toolbox
+
+Scripts have access to the full execution environment:
+- **Bash:** `jq`, `grep`, `awk`, `sed`, `find`, `diff`, `wc`, piping and composition
+- **Python:** Full standard library plus PEP 723 inline-declared dependencies (`tiktoken`, `jsonschema`, `pyyaml`, etc.)
+- **System tools:** `git` for history/diff/blame, filesystem operations
+
+### The --help Pattern
+
+All scripts use PEP 723 metadata and implement `--help`. Prompts can reference `scripts/foo.py --help` instead of inlining interface details — single source of truth, saves prompt tokens.
+
+---
+
+## Script Output Standard
+
+All scripts MUST output structured JSON:
+
+```json
+{
+  "script": "script-name",
+  "version": "1.0.0",
+  "skill_path": "/path/to/skill",
+  "timestamp": "2025-03-08T10:30:00Z",
+  "status": "pass|fail|warning",
+  "findings": [
+    {
+      "severity": "critical|high|medium|low|info",
+      "category": "structure|security|performance|consistency",
+      "location": {"file": "SKILL.md", "line": 42},
+      "issue": "Clear description",
+      "fix": "Specific action to resolve"
+    }
+  ],
+  "summary": {
+    "total": 0,
+    "critical": 0,
+    "high": 0,
+    "medium": 0,
+    "low": 0
+  }
+}
+```
+
+### Implementation Checklist
+
+- [ ] `--help` with PEP 723 metadata
+- [ ] Accepts skill path as argument
+- [ ] `-o` flag for output file (defaults to stdout)
+- [ ] Diagnostics to stderr
+- [ ] Exit codes: 0=pass, 1=fail, 2=error
+- [ ] `--verbose` flag for debugging
+- [ ] Self-contained (PEP 723 for dependencies)
+- [ ] No interactive prompts, no network dependencies
+- [ ] Valid JSON to stdout
+- [ ] Tests in `scripts/tests/`

_bmad/bmb/bmad-workflow-builder/references/skill-best-practices.md

@@ -0,0 +1,109 @@
+# Skill Authoring Best Practices
+
+For field definitions and description format, see `./references/standard-fields.md`. For quality dimensions, see `./references/quality-dimensions.md`.
+
+## Core Philosophy: Outcome-Based Authoring
+
+Skills should describe **what to achieve**, not **how to achieve it**. The LLM is capable of figuring out the approach — it needs to know the goal, the constraints, and the why.
+
+**The test for every instruction:** Would removing this cause the LLM to produce a worse outcome? If the LLM would do it anyway — or if it's just spelling out mechanical steps — cut it.
+
+### Outcome vs Prescriptive
+
+| Prescriptive (avoid) | Outcome-based (prefer) |
+|---|---|
+| "Step 1: Ask about goals. Step 2: Ask about constraints. Step 3: Summarize and confirm." | "Ensure the user's vision is fully captured — goals, constraints, and edge cases — before proceeding." |
+| "Load config. Read user_name. Read communication_language. Greet the user by name in their language." | "Load available config and greet the user appropriately." |
+| "Create a file. Write the header. Write section 1. Write section 2. Save." | "Produce a report covering X, Y, and Z." |
+
+The prescriptive versions miss requirements the author didn't think of. The outcome-based versions let the LLM adapt to the actual situation.
+
+### Why This Works
+
+- **Why over what** — When you explain why something matters, the LLM adapts to novel situations. When you just say what to do, it follows blindly even when it shouldn't.
+- **Context enables judgment** — Give domain knowledge, constraints, and goals. The LLM figures out the approach. It's better at adapting to messy reality than any script you could write.
+- **Prescriptive steps create brittleness** — When reality doesn't match the script, the LLM either follows the wrong script or gets confused. Outcomes let it adapt.
+- **Every instruction should carry its weight** — If the LLM would do it anyway, the instruction is noise. If the LLM wouldn't know to do it without being told, that's signal.
+
+### When Prescriptive Is Right
+
+Reserve exact steps for **fragile operations** where getting it wrong has consequences — script invocations, exact file paths, specific CLI commands, API calls with precise parameters. These need low freedom because there's one right way to do them.
+
+| Freedom | When | Example |
+|---------|------|---------|
+| **High** (outcomes) | Multiple valid approaches, LLM judgment adds value | "Ensure the user's requirements are complete" |
+| **Medium** (guided) | Preferred approach exists, some variation OK | "Present findings in a structured report with an executive summary" |
+| **Low** (exact) | Fragile, one right way, consequences for deviation | `python3 scripts/scan-path-standards.py {skill-path}` |
+
+## Patterns
+
+These are patterns that naturally emerge from outcome-based thinking. Apply them when they fit — they're not a checklist.
+
+### Soft Gate Elicitation
+
+At natural transitions, invite contribution without demanding it: "Anything else, or shall we move on?" Users almost always remember one more thing when given a graceful exit ramp. This produces richer artifacts than rigid section-by-section questioning.
+
+### Intent-Before-Ingestion
+
+Understand why the user is here before scanning documents or project context. Intent gives you the relevance filter — without it, scanning is noise.
+
+### Capture-Don't-Interrupt
+
+When users provide information beyond the current scope, capture it for later rather than redirecting. Users in creative flow share their best insights unprompted — interrupting loses them.
+
+### Dual-Output: Human Artifact + LLM Distillate
+
+Artifact-producing skills can output both a polished human-facing document and a token-efficient distillate for downstream LLM consumption. The distillate captures overflow, rejected ideas, and detail that doesn't belong in the human doc but has value for the next workflow. Always optional.
+
+### Parallel Review Lenses
+
+Before finalizing significant artifacts, fan out reviewers with different perspectives — skeptic, opportunity spotter, domain-specific lens. If subagents aren't available, do a single critical self-review pass. Multiple perspectives catch blind spots no single reviewer would.
+
+### Three-Mode Architecture (Guided / Yolo / Headless)
+
+Consider whether the skill benefits from multiple execution modes:
+
+| Mode | When | Behavior |
+|------|------|----------|
+| **Guided** | Default | Conversational discovery with soft gates |
+| **Yolo** | "just draft it" | Ingest everything, draft complete artifact, then refine |
+| **Headless** | `--headless` / `-H` | Complete the task without user input, using sensible defaults |
+
+Not all skills need all three. But considering them during design prevents locking into a single interaction model.
+
+### Graceful Degradation
+
+Every subagent-dependent feature should have a fallback path. A skill that hard-fails without subagents is fragile — one that falls back to sequential processing works everywhere.
+
+### Verifiable Intermediate Outputs
+
+For complex tasks with consequences: plan → validate → execute → verify. Create a verifiable plan before executing, validate with scripts where possible. Catches errors early and makes the work reversible.
+
+## Writing Guidelines
+
+- **Consistent terminology** — one term per concept, stick to it
+- **Third person** in descriptions — "Processes files" not "I help process files"
+- **Descriptive file names** — `form_validation_rules.md` not `doc2.md`
+- **Forward slashes** in all paths — cross-platform
+- **One level deep** for reference files — SKILL.md → reference.md, never chains
+- **TOC for long files** — >100 lines
+
+## Anti-Patterns
+
+| Anti-Pattern | Fix |
+|---|---|
+| Numbered steps for things the LLM would figure out | Describe the outcome and why it matters |
+| Explaining how to load config (the mechanic) | List the config keys and their defaults (the outcome) |
+| Prescribing exact greeting/menu format | "Greet the user and present capabilities" |
+| Spelling out headless mode in detail | "If headless, complete without user input" |
+| Too many options upfront | One default with escape hatch |
+| Deep reference nesting (A→B→C) | Keep references 1 level from SKILL.md |
+| Inconsistent terminology | Choose one term per concept |
+| Scripts that classify meaning via regex | Intelligence belongs in prompts, not scripts |
+
+## Scripts in Skills
+
+- **Execute vs reference** — "Run `analyze.py`" (execute) vs "See `analyze.py` for the algorithm" (read)
+- **Document constants** — explain why `TIMEOUT = 30`, not just what
+- **PEP 723 for Python** — self-contained with inline dependency declarations
+- **MCP tools** — use fully qualified names: `ServerName:tool_name`

_bmad/bmb/bmad-workflow-builder/references/standard-fields.md

@@ -0,0 +1,129 @@
+# Standard Workflow/Skill Fields
+
+## Frontmatter Fields
+
+Only these fields go in the YAML frontmatter block:
+
+| Field | Description | Example |
+|-------|-------------|---------|
+| `name` | Full skill name (kebab-case, same as folder name) | `bmad-workflow-builder`, `bmad-validate-json` |
+| `description` | [5-8 word summary]. [Use when user says 'X' or 'Y'.] | See Description Format below |
+
+## Content Fields (All Types)
+
+These are used within the SKILL.md body — never in frontmatter:
+
+| Field | Description | Example |
+|-------|-------------|---------|
+| `role-guidance` | Brief expertise primer | "Act as a senior DevOps engineer" |
+| `module-code` | Module code (if module-based) | `bmb`, `cis` |
+
+## Simple Utility Fields
+
+| Field | Description | Example |
+|-------|-------------|---------|
+| `input-format` | What it accepts | JSON file path, stdin text |
+| `output-format` | What it returns | Validated JSON, error report |
+| `standalone` | Fully standalone, no config needed? | true/false |
+| `composability` | How other skills use it | "Called by quality scanners for validation" |
+
+## Simple Workflow Fields
+
+| Field | Description | Example |
+|-------|-------------|---------|
+| `steps` | Numbered inline steps | "1. Load config 2. Read input 3. Process" |
+| `tools-used` | CLIs/tools/scripts | gh, jq, python scripts |
+| `output` | What it produces | PR, report, file |
+
+## Complex Workflow Fields
+
+| Field | Description | Example |
+|-------|-------------|---------|
+| `stages` | Named numbered stages | "01-discover, 02-plan, 03-build" |
+| `progression-conditions` | When stages complete | "User approves outline" |
+| `headless-mode` | Supports autonomous? | true/false |
+| `config-variables` | Beyond core vars | `planning_artifacts`, `output_folder` |
+| `output-artifacts` | What it creates (output-location) | "PRD document", "agent skill" |
+
+## Overview Section Format
+
+The Overview is the first section after the title — it primes the AI for everything that follows.
+
+**3-part formula:**
+1. **What** — What this workflow/skill does
+2. **How** — How it works (approach, key stages)
+3. **Why/Outcome** — Value delivered, quality standard
+
+**Templates by skill type:**
+
+**Complex Workflow:**
+```markdown
+This skill helps you {outcome} through {approach}. Act as {role-guidance}, guiding users through {key stages}. Your output is {deliverable}.
+```
+
+**Simple Workflow:**
+```markdown
+This skill {what it does} by {approach}. Act as {role-guidance}. Use when {trigger conditions}. Produces {output}.
+```
+
+**Simple Utility:**
+```markdown
+This skill {what it does}. Use when {when to use}. Returns {output format} with {key feature}.
+```
+
+## SKILL.md Description Format
+
+The frontmatter `description` is the PRIMARY trigger mechanism — it determines when the AI invokes this skill. Most BMad skills are **explicitly invoked** by name (`/skill-name` or direct request), so descriptions should be conservative to prevent accidental triggering.
+
+**Format:** Two parts, one sentence each:
+```
+[What it does in 5-8 words]. [Use when user says 'specific phrase' or 'specific phrase'.]
+```
+
+**The trigger clause** uses one of these patterns depending on the skill's activation style:
+- **Explicit invocation (default):** `Use when the user requests to 'create a PRD' or 'edit an existing PRD'.` — Quotes around specific phrases the user would actually say. Conservative — won't fire on casual mentions.
+- **Organic/reactive:** `Trigger when code imports anthropic SDK, or user asks to use Claude API.` — For lightweight skills that should activate on contextual signals, not explicit requests.
+
+**Examples:**
+
+Good (explicit): `Builds workflows and skills through conversational discovery. Use when the user requests to 'build a workflow', 'modify a workflow', or 'quality check workflow'.`
+
+Good (organic): `Initializes BMad project configuration. Trigger when any skill needs module-specific configuration values, or when setting up a new BMad project.`
+
+Bad: `Helps with PRDs and product requirements.` — Too vague, would trigger on any mention of PRD even in passing conversation.
+
+Bad: `Use on any mention of workflows, building, or creating things.` — Over-broad, would hijack unrelated conversations.
+
+**Default to explicit invocation** unless the user specifically describes organic/reactive activation during discovery.
+
+## Role Guidance Format
+
+Every generated workflow SKILL.md includes a brief role statement in the Overview or as a standalone line:
+```markdown
+Act as {role-guidance}. {brief expertise/approach description}.
+```
+This provides quick prompt priming for expertise and tone. Workflows may also use full Identity/Communication Style/Principles sections when personality serves the workflow's purpose.
+
+## Path Rules
+
+### Skill-Internal Files
+
+All references to files within the skill use `./` prefix:
+- `./references/reference.md`
+- `./references/discover.md`
+- `./scripts/validate.py`
+
+This distinguishes skill-internal files from `{project-root}` paths — without the `./` prefix the LLM may confuse them.
+
+### Project `_bmad` Paths
+Use `{project-root}/_bmad/...`:
+- `{project-root}/_bmad/planning/prd.md`
+
+### Config Variables
+Use directly — they already contain `{project-root}` in their resolved values:
+- `{output_folder}/file.md`
+- `{planning_artifacts}/prd.md`
+
+**Never:**
+- `{project-root}/{output_folder}/file.md` (WRONG — double-prefix, config var already has path)
+- `_bmad/planning/prd.md` (WRONG — bare `_bmad` must have `{project-root}` prefix)

_bmad/bmb/bmad-workflow-builder/references/template-substitution-rules.md

@@ -0,0 +1,32 @@
+# Template Substitution Rules
+
+The SKILL-template provides a minimal skeleton: frontmatter, overview, and activation with config loading. Everything beyond that is crafted by the builder based on what was learned during discovery and requirements phases.
+
+## Frontmatter
+
+- `{module-code-or-empty}` → Module code prefix with hyphen (e.g., `bmb-`) or empty for standalone
+- `{skill-name}` → Skill functional name (kebab-case)
+- `{skill-description}` → Two parts: [5-8 word summary]. [trigger phrases]
+
+## Module Conditionals
+
+### For Module-Based Skills
+- `{if-module}` ... `{/if-module}` → Keep the content inside
+- `{if-standalone}` ... `{/if-standalone}` → Remove the entire block including markers
+- `{module-code}` → Module code without trailing hyphen (e.g., `bmb`)
+- `{module-setup-skill}` → Name of the module's setup skill (e.g., `bmad-builder-setup`)
+
+### For Standalone Skills
+- `{if-module}` ... `{/if-module}` → Remove the entire block including markers
+- `{if-standalone}` ... `{/if-standalone}` → Keep the content inside
+
+## Beyond the Template
+
+The builder determines the rest of the skill structure — body sections, phases, stages, scripts, external skills, headless mode, role guidance — based on the skill type classification and requirements gathered during the build process. The template intentionally does not prescribe these; the builder has the context to craft them.
+
+## Path References
+
+All generated skills use `./` prefix for skill-internal paths:
+- `./references/{reference}.md` — Reference documents loaded on demand
+- `./references/{stage}.md` — Stage prompts (complex workflows)
+- `./scripts/` — Python/shell scripts for deterministic operations