Add BMAD commands, skills, and module files from piSetup

2026-04-22 19:46:48 -04:00
parent a4dfe0cba6
commit fa7055d3d8
1199 changed files with 199695 additions and 0 deletions
@@ -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.
@@ -0,0 +1,508 @@
+# BMad Module Workflows
+
+Advanced patterns for BMad module workflows — long-running, multi-stage processes with progressive disclosure, config integration, and compaction survival.
+
+---
+
+## Workflow Persona: Facilitator Model
+
+BMad workflows treat the human operator as the expert. The agent's role is **facilitator**, not replacement.
+
+**Principles:**
+- Ask clarifying questions when requirements are ambiguous
+- Present options with trade-offs, don't assume preferences
+- Validate decisions before executing irreversible actions
+- The operator knows their domain; the workflow knows the process
+
+**Example voice:**
+```markdown
+## Discovery
+I found 3 API endpoints that could handle this. Which approach fits your use case?
+
+**Option A**: POST /bulk-import — Faster, but no validation until complete
+**Option B**: POST /validate + POST /import — Slower, but catches errors early
+**Option C**: Streaming import — Best of both, requires backend support
+
+Which would you prefer?
+```
+
+---
+
+## Config Reading and Integration
+
+Workflows read config values from `{project-root}/_bmad/config.yaml` and `config.user.yaml`. The loading behavior differs based on whether the skill is part of a module or standalone.
+
+### Config Loading Pattern
+
+**Module-based skills** — load config with fallback and setup skill awareness:
+```
+Load config from {project-root}/_bmad/config.yaml ({module-code} section) and config.user.yaml.
+If config is missing:
+  - Inform the user that the module setup skill ({module-setup-skill}) is available for initial setup
+  - Continue with sensible fallback values for each variable
+```
+
+**Standalone skills** — load config best-effort:
+```
+Load config from {project-root}/_bmad/config.yaml and config.user.yaml if available.
+If config is missing:
+  - Continue with fallback values — no mention of a setup skill
+```
+
+Store config values in memory as `{var_name}` for use in prompts.
+
+### Required Core Variables
+
+Load core config variables (user preferences, language, output locations) with sensible defaults. If the workflow creates documents, include document output language.
+
+**Example for BMB workflow (creates documents, has output var):**
+```
+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/
+```
+
+**Example for analysis workflow (no documents, has output var):**
+```
+vars: user_name:BMad,communication_language:English,output_folder:{project-root}/_bmad-output,analysis_output_folder:{project-root}/_bmad-output/analysis/
+```
+
+**Example for processing workflow (no documents, no output var):**
+```
+vars: user_name:BMad,communication_language:English,output_folder:{project-root}/_bmad-output
+```
+
+### Using Config Values in Prompts
+
+Each prompt file should establish communication language and relevant output settings at the top.
+
+**Use throughout prompts:**
+```markdown
+"Creating documentation in {document_output_language}..."  ← ONLY if creates documents
+"Writing output to {bmad_builder_output_folder}/report.md" ← ONLY if has output var
+"Connecting to API at {my_module_api_url}..."
+```
+
+---
+
+## {project_root} Pattern for Portable Paths
+
+Artifacts MUST use `{project_root}` for paths so the skill works regardless of install location (user directory or project).
+
+### Path Pattern
+
+```
+{project_root}/docs/foo.md         → Correct (portable)
+./docs/foo.md                      → Wrong (breaks if skill in user dir)
+~/my-project/docs/foo.md           → Wrong (not portable)
+/bizarre/absolute/path/foo.md      → Wrong (not portable)
+```
+
+### Writing Artifacts
+
+```markdown
+1. Create the artifact at {project_root}/docs/architecture.md
+2. Update {project_root}/CHANGELOG.md with entry
+3. Copy template to {project_root}/.bmad-cache/template.md
+```
+
+### {project_root} Resolution
+
+`{project_root}` is automatically resolved to the directory where the workflow was launched. This ensures:
+- Skills work whether installed globally or per-project
+- Multiple projects can use the same skill without conflict
+- Artifact paths are always relative to the active project
+
+---
+
+## Long-Running Workflows: Compaction Survival
+
+Workflows that run long (many steps, large context) may trigger context compaction. Critical state MUST be preserved in output files.
+
+### The Document-Itself Pattern
+
+**The output document is the cache.** Write directly to the file you're creating, updating it progressively as the workflow advances.
+
+The document stores both content and context:
+- **YAML front matter** — paths to input files used (for recovery after compaction)
+- **Draft sections** — progressive content as it's built
+- **Status marker** — which stage is complete (for resumption)
+
+This avoids:
+- File collisions when working on multiple PRDs/research projects simultaneously
+- Extra `_bmad-cache` folder overhead
+- State synchronization complexity
+
+### Draft Document Structure
+
+```markdown
+---
+title: "Analysis: Research Topic"
+status: "analysis"  # discovery | planning | analysis | synthesis | polish
+inputs:
+  - "{project_root}/docs/brief.md"
+  - "{project_root}/data/sources.json"
+created: "2025-03-02T10:00:00Z"
+updated: "2025-03-02T11:30:00Z"
+---
+
+# Analysis: Research Topic
+
+## Discovery
+[content from stage 1...]
+
+## Analysis
+[content from stage 2...]
+
+---
+
+*Last updated: Stage 2 complete*
+```
+
+### Input Tracking Pattern
+
+**Stage 1: Initialize document with inputs**
+```markdown
+## Stage 1: Discovery
+1. Gather sources and identify input files
+2. Create output document with YAML front matter:
+```yaml
+---
+title: "{document_title}"
+status: "discovery"
+inputs:
+  - "{relative_path_to_input_1}"
+  - "{relative_path_to_input_2}"
+created: "{timestamp}"
+updated: "{timestamp}"
+---
+```
+3. Write discovery content to document
+4. Present summary to user
+```
+
+**Stage 2+: Reload context if compacted**
+
+Each stage after the first should begin by reading the output document to recover context. If compacted, re-read input files listed in the YAML front matter.
+
+```markdown
+## Stage 1: Research
+1. Gather sources
+2. **Write findings to {project_root}/docs/research-topic.md**
+3. Present summary to user
+
+## Stage 2: Analysis
+1. **Read {project_root}/docs/research-topic.md** (survives compaction)
+2. Analyze patterns
+3. **Append/insert analysis into the same file**
+
+## Stage 3: Synthesis
+1. Read the growing document
+2. Synthesize into final structure
+3. **Update the same file in place**
+
+## Stage 4: Final Polish
+1. Spawn a subagent to polish the completed document:
+   - Cohesion check
+   - Redundancy removal
+   - Contradiction detection and fixes
+   - Add TOC if long document
+2. Write final version to {project_root}/docs/research-topic.md
+```
+
+### When to Use This Pattern
+
+**Guided flows with long documents:** Always write updates to the document itself at each stage.
+
+**Yolo flows with multiple turns:** If the workflow takes multiple conversational turns, write to the output file progressively.
+
+**Single-pass yolo:** Can wait to write final output if the entire response fits in one turn.
+
+### Progressive Document Structure
+
+Each stage appends to or restructures the document:
+
+```markdown
+## Initial Stage
+# Document Title
+
+## Section 1: Initial Research
+[content...]
+
+---
+
+## Second Stage (reads file, appends)
+# Document Title
+
+## Section 1: Initial Research
+[existing content...]
+
+## Section 2: Analysis
+[new content...]
+
+---
+
+## Third Stage (reads file, restructures)
+# Document Title
+
+## Executive Summary
+[ synthesized from sections ]
+
+## Background
+[ section 1 content ]
+
+## Analysis
+[ section 2 content ]
+```
+
+### Final Polish Subagent
+
+At workflow completion, spawn a subagent for final quality pass:
+
+```markdown
+## Final Polish
+
+Launch a general-purpose agent with:
+```
+Task: Polish {output_file_path}
+
+Actions:
+1. Check cohesion - do sections flow logically?
+2. Find and remove redundancy
+3. Detect contradictions and fix them
+4. If document is >5 sections, add a TOC at the top
+5. Ensure consistent formatting and tone
+
+Write the polished version back to the same file.
+```
+
+### Compaction Recovery Pattern
+
+Each stage after the first should begin by reading the output document to recover context. If compacted, re-read input files listed in the YAML front matter.
+
+### When NOT to Use This Pattern
+
+- **Short, single-turn outputs:** Just write once at the end
+- **Purely conversational workflows:** No persistent document needed
+- **Multiple independent artifacts:** Each gets its own file; write each directly
+
+---
+
+## Sequential Progressive Disclosure
+
+Place numbered prompt files at the skill root when:
+- Multi-phase workflow with ordered questions
+- Input of one phase affects the next
+- User requires specific sequence
+- Workflow is long-running and stages shouldn't be visible upfront
+
+### Prompt File Structure
+
+```
+my-workflow/
+├── SKILL.md
+├── 01-discovery.md           # Stage 1: Gather requirements, start output doc
+├── 02-planning.md            # Stage 2: Create plan (uses discovery output)
+├── 03-execution.md           # Stage 3: Execute (uses plan, updates output)
+├── 04-review.md              # Stage 4: Review and polish final output
+└── references/
+    └── stage-templates.md
+```
+
+### Progression Conditions
+
+Each prompt file specifies when to proceed:
+
+```markdown
+# 02-planning.md
+
+## Prerequisites
+- Discovery complete (output doc exists and has discovery section)
+- User approved scope (user confirmed: proceed)
+
+## On Activation
+1. Read the output doc to get discovery context
+2. Generate plan based on discovered requirements
+3. **Append/insert plan section into the output doc**
+4. Present plan summary to user
+
+## Progression Condition
+Proceed to execution stage when user confirms: "Proceed with plan" OR user provides modifications
+
+## On User Approval
+Route to 03-execution.md
+```
+
+### SKILL.md Routes to Prompt Files
+
+Main SKILL.md is minimal — just routing logic:
+
+```markdown
+## Workflow Entry
+
+1. Load config from {project-root}/_bmad/bmb/config.yaml
+
+2. Check if workflow in progress:
+   - If output doc exists (user specifies path or we prompt):
+     - Read doc to determine current stage
+     - Resume from last completed section
+   - Else: Start at 01-discovery.md
+
+3. Route to appropriate prompt file based on stage
+```
+
+### When NOT to Use Separate Prompt Files
+
+Keep inline in SKILL.md when:
+- Simple skill (session-long context fits)
+- Well-known domain tool usage
+- Single-purpose utility
+- All stages are independent or can be visible upfront
+
+---
+
+## Module Metadata Reference
+
+BMad module workflows require extended frontmatter metadata. See `references/metadata-reference.md` for the metadata template, field explanations, and comparisons between standalone skills and module workflows.
+
+---
+
+## Workflow Architecture Checklist
+
+Before finalizing a BMad module workflow, verify:
+
+- [ ] **Facilitator persona**: Does the workflow treat the operator as expert?
+- [ ] **Config integration**: Are language, output locations, and module props read and used?
+- [ ] **Portable paths**: All artifact paths use `{project_root}`?
+- [ ] **Continuous output**: Does each stage write to the output document directly (survives compaction)?
+- [ ] **Document-as-cache**: Output doc has YAML front matter with `status` and `inputs` for recovery?
+- [ ] **Input tracking**: Does front matter list relative paths to all input files used?
+- [ ] **Final polish**: Does workflow include a subagent polish step at the end?
+- [ ] **Progressive disclosure**: Are stages in `./references/` with clear progression conditions?
+- [ ] **Metadata complete**: All bmad-* fields present and accurate?
+- [ ] **Recovery pattern**: Can the workflow resume by reading the output doc front matter?
+
+---
+
+## Example: Complete BMad Workflow Skeleton
+
+```
+my-module-workflow/
+├── SKILL.md                              # Routing + entry logic
+├── 01-discovery.md                       # Gather requirements
+├── 02-planning.md                        # Create plan
+├── 03-execution.md                       # Execute
+├── 04-review.md                          # Review results
+├── references/
+│   └── templates.md                      # Stage templates
+└── scripts/
+    └── validator.sh                      # Output validation
+```
+
+**SKILL.md** (minimal routing):
+```yaml
+---
+name: bmad-mymodule-workflow
+description: Complex multi-stage workflow for my module. Use when user requests to 'run my module workflow' or 'create analysis report'.
+---
+
+## Workflow Entry
+
+1. Load config from `{project-root}/_bmad/config.yaml` (`mymod` section) and `config.user.yaml`. If config is missing, inform that `bmad-mymodule-setup` is available for initial setup, then continue with fallbacks:
+   - `user_name` — fallback: omit
+   - `communication_language` — fallback: match the user's language
+   - `document_output_language` — fallback: match the user's language
+   - `my_output_folder` — fallback: `{project-root}/_bmad-output/mymodule`
+
+2. Ask user for output document path (or suggest {my_output_folder}/analysis-{timestamp}.md)
+
+3. Check if doc exists:
+   - If yes: read to determine current stage, resume
+   - If no: start at 01-discovery.md
+
+4. Route to appropriate prompt file based on stage
+```
+
+**01-discovery.md**:
+```markdown
+Language: {communication_language}
+Output Language: {document_output_language}
+Output Location: {my_output_folder}
+
+## Discovery
+
+1. What are we building?
+2. What are the constraints?
+3. What input files should we reference?
+
+**Create**: {output_doc_path} with:
+```markdown
+---
+title: "Analysis: {topic}"
+status: "discovery"
+inputs:
+  - "{relative_path_to_input_1}"
+  - "{relative_path_to_input_2}"
+created: "{timestamp}"
+updated: "{timestamp}"
+---
+
+# Analysis: {topic}
+
+## Discovery
+[findings...]
+
+---
+
+*Status: Stage 1 complete*
+```
+
+## Progression
+When complete → 02-planning.md
+```
+
+**02-planning.md**:
+```markdown
+Language: {communication_language}
+Output Language: {document_output_language}
+
+## Planning Start
+
+1. Read {output_doc_path}
+2. Parse YAML front matter — reload all `inputs` to restore context
+3. Verify status is "discovery"
+
+## Planning
+1. Generate plan based on discovery
+2. Update {output_doc_path}:
+   - Update status to "planning"
+   - Append planning section
+
+## Progression
+When complete → 03-execution.md
+```
+
+**04-review.md**:
+```markdown
+Language: {communication_language}
+Output Language: {document_output_language}
+
+## Final Polish
+
+1. Read the complete output doc
+2. Launch a general-purpose agent:
+```
+Task: Polish {output_doc_path}
+
+Actions:
+1. Check cohesion - do sections flow logically?
+2. Find and remove redundancy
+3. Detect contradictions and fix them
+4. If document is >5 sections, add a TOC at the top
+5. Ensure consistent formatting and tone
+6. Update YAML status to "complete" and remove draft markers
+
+Write the polished version back to the same file.
+```
+
+## Progression
+When complete → present final result to user
+```
@@ -0,0 +1,45 @@
+# Quality Dimensions — Quick Reference
+
+Six dimensions to keep in mind when building skills. The quality scanners check these automatically during optimization — this is a mental checklist for the build phase.
+
+## 1. Informed Autonomy
+
+The executing agent needs enough context to make judgment calls when situations don't match the script. The Overview section 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
+
+## 2. 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. Scripts have access to full bash, Python with standard library plus PEP 723 dependencies, and system tools — think broadly about what can be offloaded.
+
+## 3. 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: acceptable if focused
+
+## 4. 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 and examples.
+
+## 5. 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.
+
+## 6. 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 — the prompt-craft scanner distinguishes between them.
@@ -0,0 +1,349 @@
+# 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.
+
+---
+
+## Section 1: How to Spot Script Opportunities
+
+### The Determinism Test
+
+Ask two questions about any operation:
+
+1. **Given identical input, will it always produce identical output?** If yes, it's a script candidate.
+2. **Could you write a unit test with expected output?** If yes, it's definitely a script.
+
+**Script territory:** The operation has no ambiguity — same input, same result, every time.
+**Prompt territory:** The operation requires interpreting meaning, tone, or context — reasonable people could disagree on the output.
+
+### The Judgment Boundary
+
+| Scripts Handle | Prompts Handle |
+|----------------|----------------|
+| Fetch | Interpret |
+| Transform | Classify (with ambiguity) |
+| Validate | Create |
+| Count | Decide (with incomplete info) |
+| Parse | Evaluate quality |
+| Compare | Synthesize meaning |
+| Extract | Assess tone/style |
+| Format | Generate recommendations |
+| Check structure | Weigh tradeoffs |
+
+### Pattern Recognition Checklist
+
+When you see these verbs or patterns in a workflow's requirements, think scripts first:
+
+| Signal Verb / Pattern | Script Type | Example |
+|----------------------|-------------|---------|
+| validate | Validation script | "Validate frontmatter fields exist" |
+| count | Metric script | "Count tokens per file" |
+| extract | Data extraction | "Extract all config variable references" |
+| convert / transform | Transformation script | "Convert stage definitions to graph" |
+| compare | Comparison script | "Compare prompt frontmatter vs SKILL.md references" |
+| scan for | Pattern scanning | "Scan for orphaned template artifacts" |
+| check structure | File structure checker | "Check skill directory has required files" |
+| against schema | Schema validation | "Validate output against JSON schema" |
+| graph / map dependencies | Dependency analysis | "Map skill-to-skill dependencies" |
+| list all | Enumeration script | "List all resource files loaded by prompts" |
+| detect pattern | Pattern detector | "Detect subagent delegation patterns" |
+| diff / changes between | Diff analysis | "Show what changed between versions" |
+
+### The Outside-the-Box Test
+
+Scripts are not limited to validation. Push your thinking:
+
+- **Data gathering as script:** Could a script collect structured data (file sizes, dependency lists, config values) and return JSON for the LLM to interpret? The LLM gets pre-digested facts instead of reading raw files.
+- **Pre-processing:** Could a script reduce what the LLM needs to read? Extract only the relevant sections, strip boilerplate, summarize structure.
+- **Post-processing validation:** Could a script validate LLM output after generation? Check that generated YAML parses, that referenced files exist, that naming conventions are followed.
+- **Metric collection:** Could scripts count, measure, and tabulate so the LLM makes decisions based on numbers it didn't have to compute? Token counts, file counts, complexity scores — feed these to LLM judgment without making the LLM count.
+- **Workflow stage analysis:** Could a script parse stage definitions and progression conditions, giving the LLM a structural map without it needing to parse markdown?
+
+### Your Toolbox
+
+Scripts have access to the full capabilities of the execution environment. Think broadly — if you can express the logic as deterministic code, it's a script candidate.
+
+**Bash:** Full shell power — `jq`, `grep`, `awk`, `sed`, `find`, `diff`, `wc`, `sort`, `uniq`, `curl`, plus piping and composition. Great for file discovery, text processing, and orchestrating other scripts.
+
+**Python:** The entire standard library — `json`, `yaml`, `pathlib`, `re`, `argparse`, `collections`, `difflib`, `ast`, `csv`, `xml.etree`, `textwrap`, `dataclasses`, and more. Plus PEP 723 inline-declared dependencies for anything else: `tiktoken` for accurate token counting, `jsonschema` for schema validation, `pyyaml` for YAML parsing, etc.
+
+**System tools:** `git` commands for history, diff, blame, and log analysis. Filesystem operations for directory scanning and structure validation. Process execution for orchestrating multi-script pipelines.
+
+### The --help Pattern
+
+All scripts use PEP 723 metadata and implement `--help`. This creates a powerful integration pattern for prompts:
+
+Instead of inlining a script's interface details into a prompt, the prompt can simply say:
+
+> Run `scripts/foo.py --help` to understand its inputs and outputs, then invoke appropriately.
+
+This saves tokens in the prompt and keeps a single source of truth for the script's API. When a script's interface changes, the prompt doesn't need updating — `--help` always reflects the current contract.
+
+---
+
+## Section 2: Script Opportunity Catalog
+
+Each entry follows the format: What it does, Why it matters for workflows, What it checks, What it outputs, and Implementation notes.
+
+---
+
+### 1. Frontmatter Validator
+
+**What:** Validate SKILL.md frontmatter structure and content.
+
+**Why:** Frontmatter drives skill triggering and routing. Malformed frontmatter means the skill never activates or activates incorrectly.
+
+**Checks:**
+- `name` exists and is kebab-case
+- `description` exists and follows "Use when..." pattern
+- No forbidden fields or reserved prefixes
+- Optional fields have valid values if present
+
+**Output:** JSON with pass/fail per field, line numbers for errors.
+
+**Implementation:** Python with argparse, no external deps needed. Parse YAML frontmatter between `---` delimiters.
+
+---
+
+### 2. Template Artifact Scanner
+
+**What:** Scan all skill files for orphaned template substitution artifacts.
+
+**Why:** The build process may leave behind `{if-autonomous}`, `{displayName}`, `{skill-name}`, or other placeholders that should have been replaced. These cause runtime confusion.
+
+**Checks:**
+- Scan all `.md` files for `{placeholder}` patterns
+- Distinguish real config variables (loaded at runtime) from build-time artifacts
+- Flag any that don't match known runtime variables
+
+**Output:** JSON with file path, line number, artifact text, and whether it looks intentional.
+
+**Implementation:** Bash script with `grep` and `jq` for JSON output, or Python with regex.
+
+---
+
+### 3. Prompt Frontmatter Comparator
+
+**What:** Compare prompt file frontmatter against SKILL.md stage references.
+
+**Why:** Misalignment between prompts and SKILL.md causes routing failures — the skill references a stage it can't deliver, or has a prompt that's never reachable.
+
+**Checks:**
+- Every prompt file at root has frontmatter with `name`, `description`, `menu-code`
+- Every stage referenced in SKILL.md has a corresponding prompt file
+- Flag orphaned prompts not referenced in SKILL.md
+
+**Output:** JSON with mismatches, missing files, orphaned prompts.
+
+**Implementation:** Python, reads SKILL.md and all prompt `.md` files at skill root.
+
+---
+
+### 4. Token Counter
+
+**What:** Count approximate token counts for each file in a skill.
+
+**Why:** Identify verbose files that need optimization. Catch skills that exceed context window budgets. Understand where token budget is spent across prompts, resources, and the SKILL.md.
+
+**Checks:**
+- Total tokens per `.md` file (approximate: chars / 4, or accurate via tiktoken)
+- Code block tokens vs prose tokens
+- Cumulative token cost of full skill activation (SKILL.md + loaded resources + initial prompt)
+
+**Output:** JSON with file path, token count, percentage of total, and a sorted ranking.
+
+**Implementation:** Python. Use `tiktoken` (PEP 723 dependency) for accuracy, or fall back to character approximation.
+
+---
+
+### 5. Dependency Graph Generator
+
+**What:** Map dependencies between the current skill and external skills it invokes.
+
+**Why:** Understand the skill's dependency surface. Catch references to skills that don't exist or have been renamed.
+
+**Checks:**
+- Parse SKILL.md and prompts for skill invocation patterns (`invoke`, `load`, skill name references)
+- Build a dependency list with direction (this skill depends on X, Y depends on this skill)
+
+**Output:** JSON adjacency list or DOT format (GraphViz). Include whether each dependency is required or optional.
+
+**Implementation:** Python with regex for invocation pattern detection.
+
+---
+
+### 6. Stage Flow Analyzer
+
+**What:** Parse multi-stage workflow definitions to extract stage ordering, progression conditions, and routing logic.
+
+**Why:** Complex workflows define stages with specific progression conditions. Misaligned stage ordering, missing progression gates, or unreachable stages cause workflow failures that are hard to debug at runtime.
+
+**Checks:**
+- Extract all defined stages from SKILL.md and prompt files
+- Verify each stage has a clear entry condition and exit/progression condition
+- Detect unreachable stages (no path leads to them)
+- Detect dead-end stages (no progression and not marked as terminal)
+- Validate stage ordering matches the documented flow
+- Check for circular stage references
+
+**Output:** JSON with stage list, progression map, and structural warnings.
+
+**Implementation:** Python with regex for stage/condition extraction from markdown.
+
+---
+
+### 7. Config Variable Tracker
+
+**What:** Find all `{var}` references across skill files and verify they are loaded or defined.
+
+**Why:** Unresolved config variables cause runtime errors or produce literal `{var_name}` text in outputs. This is especially common after refactoring or renaming variables.
+
+**Checks:**
+- Scan all `.md` files for `{variable_name}` patterns
+- Cross-reference against variables defined in `{project-root}/_bmad/config.yaml`
+- Distinguish template variables from literal text in code blocks
+- Flag undefined variables and unused loaded variables
+
+**Output:** JSON with variable name, locations where used, and whether it's defined/loaded.
+
+**Implementation:** Python with regex scanning and config file parsing.
+
+---
+
+### 8. Resource Loading Analyzer
+
+**What:** Map which resources are loaded at which point during skill execution.
+
+**Why:** Resources loaded too early waste context. Resources never loaded are dead weight in the skill directory. Understanding the loading sequence helps optimize token budget.
+
+**Checks:**
+- Parse SKILL.md and prompts for `Load resource` / `Read` / file reference patterns
+- Map each resource to the stage/prompt where it's first loaded
+- Identify resources in `references/` that are never referenced
+- Identify resources referenced but missing from `references/`
+- Calculate cumulative token cost at each loading point
+
+**Output:** JSON with resource file, loading trigger (which prompt/stage), and orphan/missing flags.
+
+**Implementation:** Python with regex for load-pattern detection and directory scanning.
+
+---
+
+### 9. Subagent Pattern Detector
+
+**What:** Detect whether a skill that processes multiple sources uses the BMad Advanced Context Pattern (subagent delegation).
+
+**Why:** Skills processing 5+ sources without subagent delegation risk context overflow and degraded output quality. This pattern is required for high-source-count workflows.
+
+**Checks:**
+- Count distinct source/input references in the skill
+- Look for subagent delegation patterns: "DO NOT read sources yourself", "delegate to sub-agents", `/tmp/analysis-` temp file patterns
+- Check for sub-agent output templates (50-100 token summaries)
+- Flag skills with 5+ sources that lack the pattern
+
+**Output:** JSON with source count, pattern found/missing, and recommendations.
+
+**Implementation:** Python with keyword search and context extraction.
+
+---
+
+### 10. Prompt Chain Validator
+
+**What:** Trace the chain of prompt loads through a workflow and verify every path is valid.
+
+**Why:** Workflows route between prompts based on user intent and stage progression. A broken link in the chain — a `Load foo.md` where `foo.md` doesn't exist — halts the workflow.
+
+**Checks:**
+- Extract all `Load *.md` prompt references from SKILL.md and every prompt file
+- Verify each referenced prompt file exists
+- Build a reachability map from SKILL.md entry points
+- Flag prompts that exist but are unreachable from any entry point
+
+**Output:** JSON with prompt chain map, broken links, and unreachable prompts.
+
+**Implementation:** Python with regex extraction and file existence checks.
+
+---
+
+### 11. Skill Health Check (Composite)
+
+**What:** Run all available validation scripts and aggregate results into a single report.
+
+**Why:** One command to assess overall skill quality. Useful as a build gate or pre-commit check.
+
+**Composition:** Runs scripts 1-10 in sequence, collects JSON outputs, aggregates findings by severity.
+
+**Output:** Unified JSON health report with per-script results and overall status.
+
+**Implementation:** Bash script orchestrating Python scripts, `jq` for JSON aggregation. Or a Python orchestrator using `subprocess`.
+
+---
+
+### 12. Skill Comparison Validator
+
+**What:** Compare two versions of a skill (or two skills) for structural differences.
+
+**Why:** Validate that changes during iteration didn't break structure. Useful for reviewing edits, comparing before/after optimization, or diffing a skill against a template.
+
+**Checks:**
+- Frontmatter changes
+- New or removed prompt files
+- Token count changes per file
+- Stage flow changes (for workflows)
+- Resource additions/removals
+
+**Output:** JSON with categorized changes and severity assessment.
+
+**Implementation:** Bash with `git diff` or file comparison, Python for structural analysis.
+
+---
+
+## Section 3: Script Output Standard and Implementation Checklist
+
+### Script Output Standard
+
+All scripts MUST output structured JSON for agent consumption:
+
+```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
+
+When creating new validation scripts:
+
+- [ ] Uses `--help` for documentation (PEP 723 metadata)
+- [ ] Accepts skill path as argument
+- [ ] `-o` flag for output file (defaults to stdout)
+- [ ] Writes diagnostics to stderr
+- [ ] Returns meaningful exit codes: 0=pass, 1=fail, 2=error
+- [ ] Includes `--verbose` flag for debugging
+- [ ] Self-contained (PEP 723 for Python dependencies)
+- [ ] No interactive prompts
+- [ ] No network dependencies
+- [ ] Outputs valid JSON to stdout
+- [ ] Has tests in `scripts/tests/` subfolder
@@ -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`
@@ -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)
@@ -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
@@ -0,0 +1,267 @@
+# Universal Scanner Output Schema
+
+All quality scanners — both LLM-based and deterministic lint scripts — MUST produce output conforming to this schema. No exceptions.
+
+## Top-Level Structure
+
+```json
+{
+  "scanner": "scanner-name",
+  "skill_path": "{path}",
+  "findings": [],
+  "assessments": {},
+  "summary": {
+    "total_findings": 0,
+    "by_severity": {},
+    "assessment": "1-2 sentence overall assessment"
+  }
+}
+```
+
+| Key | Type | Required | Description |
+|-----|------|----------|-------------|
+| `scanner` | string | yes | Scanner identifier (e.g., `"workflow-integrity"`, `"prompt-craft"`) |
+| `skill_path` | string | yes | Absolute path to the skill being scanned |
+| `findings` | array | yes | ALL items — issues, strengths, suggestions, opportunities. Always an array, never an object |
+| `assessments` | object | yes | Scanner-specific structured analysis (cohesion tables, health metrics, user journeys, etc.). Free-form per scanner |
+| `summary` | object | yes | Aggregate counts and brief overall assessment |
+
+## Finding Schema (7 fields)
+
+Every item in `findings[]` has exactly these 7 fields:
+
+```json
+{
+  "file": "SKILL.md",
+  "line": 42,
+  "severity": "high",
+  "category": "frontmatter",
+  "title": "Brief headline of the finding",
+  "detail": "Full context — rationale, what was observed, why it matters",
+  "action": "What to do about it — fix, suggestion, or script to create"
+}
+```
+
+| Field | Type | Required | Description |
+|-------|------|----------|-------------|
+| `file` | string | yes | Relative path to the affected file (e.g., `"SKILL.md"`, `"scripts/build.py"`). Empty string if not file-specific |
+| `line` | int\|null | no | Line number (1-based). `null` or `0` if not line-specific |
+| `severity` | string | yes | One of the severity values below |
+| `category` | string | yes | Scanner-specific category (e.g., `"frontmatter"`, `"token-waste"`, `"lint"`) |
+| `title` | string | yes | Brief headline (1 sentence). This is the primary display text |
+| `detail` | string | yes | Full context — fold rationale, observation, impact, nuance into one narrative. Empty string if title is self-explanatory |
+| `action` | string | yes | What to do — fix instruction, suggestion, or script to create. Empty string for strengths/notes |
+
+## Severity Values (complete enum)
+
+```
+critical | high | medium | low | high-opportunity | medium-opportunity | low-opportunity | suggestion | strength | note
+```
+
+**Routing rules:**
+- `critical`, `high` → "Truly Broken" section in report
+- `medium`, `low` → category-specific findings sections
+- `high-opportunity`, `medium-opportunity`, `low-opportunity` → enhancement/creative sections
+- `suggestion` → creative suggestions section
+- `strength` → strengths section (positive observations worth preserving)
+- `note` → informational observations, also routed to strengths
+
+## Assessment Sub-Structure Contracts
+
+The `assessments` object is free-form per scanner, but the HTML report renderer expects specific shapes for specific keys. These are the canonical formats.
+
+### user_journeys (enhancement-opportunities scanner)
+
+**Always an array of objects. Never an object keyed by persona.**
+
+```json
+"user_journeys": [
+  {
+    "archetype": "first-timer",
+    "summary": "Brief narrative of this user's experience",
+    "friction_points": ["moment 1", "moment 2"],
+    "bright_spots": ["what works well"]
+  }
+]
+```
+
+### autonomous_assessment (enhancement-opportunities scanner)
+
+```json
+"autonomous_assessment": {
+  "potential": "headless-ready|easily-adaptable|partially-adaptable|fundamentally-interactive",
+  "hitl_points": 3,
+  "auto_resolvable": 2,
+  "needs_input": 1,
+  "notes": "Brief assessment"
+}
+```
+
+### top_insights (enhancement-opportunities scanner)
+
+**Always an array of objects with title/detail/action (same shape as findings but without file/line/severity/category).**
+
+```json
+"top_insights": [
+  {
+    "title": "The key observation",
+    "detail": "Why it matters",
+    "action": "What to do about it"
+  }
+]
+```
+
+### cohesion_analysis (skill-cohesion / agent-cohesion scanner)
+
+```json
+"cohesion_analysis": {
+  "dimension_name": { "score": "strong|moderate|weak", "notes": "explanation" }
+}
+```
+
+Dimension names are scanner-specific (e.g., `stage_flow_coherence`, `persona_alignment`). The report renderer iterates all keys and renders a table row per dimension.
+
+### skill_identity / agent_identity (cohesion scanners)
+
+```json
+"skill_identity": {
+  "name": "skill-name",
+  "purpose_summary": "Brief characterization",
+  "primary_outcome": "What this skill produces"
+}
+```
+
+### skillmd_assessment (prompt-craft scanner)
+
+```json
+"skillmd_assessment": {
+  "overview_quality": "appropriate|excessive|missing",
+  "progressive_disclosure": "good|needs-extraction|monolithic",
+  "notes": "brief assessment"
+}
+```
+
+Agent variant adds `"persona_context": "appropriate|excessive|missing"`.
+
+### prompt_health (prompt-craft scanner)
+
+```json
+"prompt_health": {
+  "total_prompts": 3,
+  "with_config_header": 2,
+  "with_progression": 1,
+  "self_contained": 3
+}
+```
+
+### skill_understanding (enhancement-opportunities scanner)
+
+```json
+"skill_understanding": {
+  "purpose": "what this skill does",
+  "primary_user": "who it's for",
+  "assumptions": ["assumption 1", "assumption 2"]
+}
+```
+
+### stage_summary (workflow-integrity scanner)
+
+```json
+"stage_summary": {
+  "total_stages": 0,
+  "missing_stages": [],
+  "orphaned_stages": [],
+  "stages_without_progression": [],
+  "stages_without_config_header": []
+}
+```
+
+### metadata (structure scanner)
+
+Free-form key-value pairs. Rendered as a metadata block.
+
+### script_summary (scripts lint)
+
+```json
+"script_summary": {
+  "total_scripts": 5,
+  "by_type": {"python": 3, "shell": 2},
+  "missing_tests": ["script1.py"]
+}
+```
+
+### existing_scripts (script-opportunities scanner)
+
+Array of strings (script paths that already exist).
+
+## Complete Example
+
+```json
+{
+  "scanner": "workflow-integrity",
+  "skill_path": "/path/to/skill",
+  "findings": [
+    {
+      "file": "SKILL.md",
+      "line": 12,
+      "severity": "high",
+      "category": "frontmatter",
+      "title": "Missing 'description' field in frontmatter",
+      "detail": "The SKILL.md frontmatter is missing the description field. Without a description, the skill cannot be triggered reliably by the help system.",
+      "action": "Add a description with trigger phrases to the YAML frontmatter block"
+    },
+    {
+      "file": "build-process.md",
+      "line": null,
+      "severity": "strength",
+      "category": "design",
+      "title": "Excellent progressive disclosure pattern in build stages",
+      "detail": "Each stage provides exactly the context needed without front-loading information. This reduces token waste and improves LLM comprehension.",
+      "action": ""
+    },
+    {
+      "file": "SKILL.md",
+      "line": 45,
+      "severity": "medium-opportunity",
+      "category": "experience-gap",
+      "title": "No guidance for first-time users unfamiliar with build workflows",
+      "detail": "A user encountering this skill for the first time has no onboarding path. The skill assumes familiarity with stage-based workflows, which creates friction for newcomers.",
+      "action": "Add a 'Getting Started' section or link to onboarding documentation"
+    }
+  ],
+  "assessments": {
+    "stage_summary": {
+      "total_stages": 7,
+      "missing_stages": [],
+      "orphaned_stages": ["cleanup"]
+    }
+  },
+  "summary": {
+    "total_findings": 3,
+    "by_severity": {"high": 1, "medium-opportunity": 1, "strength": 1},
+    "assessment": "Well-structured skill with one critical frontmatter gap. Progressive disclosure is a notable strength."
+  }
+}
+```
+
+## DO NOT
+
+- **DO NOT** rename fields. Use exactly: `file`, `line`, `severity`, `category`, `title`, `detail`, `action`
+- **DO NOT** use `issues` instead of `findings` — the array is always called `findings`
+- **DO NOT** add fields to findings beyond the 7 defined above. Put scanner-specific structured data in `assessments`
+- **DO NOT** use separate arrays for strengths, suggestions, or opportunities — they go in `findings` with appropriate severity values
+- **DO NOT** change `user_journeys` from an array to an object keyed by persona name
+- **DO NOT** restructure assessment sub-objects — use the shapes defined above
+- **DO NOT** put free-form narrative data into `assessments` — that belongs in `detail` fields of findings or in `summary.assessment`
+
+## Self-Check Before Output
+
+Before writing your JSON output, verify:
+
+1. Is your array called `findings` (not `issues`, not `opportunities`)?
+2. Does every item in `findings` have all 7 fields: `file`, `line`, `severity`, `category`, `title`, `detail`, `action`?
+3. Are strengths in `findings` with `severity: "strength"` (not in a separate `strengths` array)?
+4. Are suggestions in `findings` with `severity: "suggestion"` (not in a separate `creative_suggestions` array)?
+5. Is `assessments` an object containing structured analysis data (not items that belong in findings)?
+6. Is `user_journeys` an array of objects (not an object keyed by persona)?
+7. Do `top_insights` items use `title`/`detail`/`action` (not `insight`/`suggestion`/`why_it_matters`)?