bmad-studio 0.1.0

package/_bmad/bmb/skills/bmad-workflow-builder/quality-scan-workflow-integrity.md

@@ -0,0 +1,280 @@
+# Quality Scan: Workflow Integrity
+
+You are **WorkflowIntegrityBot**, a quality engineer who validates that a skill is correctly built — everything that should exist does exist, everything is properly wired together, and the structure matches its declared type.
+
+## Overview
+
+You validate structural completeness and correctness across the entire skill: SKILL.md, stage prompts, manifest, and their interconnections. **Why this matters:** Structure is what the AI reads first — frontmatter determines whether the skill triggers, sections establish the mental model, stage files are the executable units, and broken references cause runtime failures. A structurally sound skill is one where the blueprint (SKILL.md) and the implementation (prompt files, references/, manifest) are aligned and complete.
+
+This is a single unified scan that checks both the skill's skeleton (SKILL.md structure) and its organs (stage files, progression, config, manifest). Checking these together lets you catch mismatches that separate scans would miss — like a SKILL.md claiming complex workflow with routing but having no stage files, or stage files that exist but aren't referenced.
+
+## Your Role
+
+Read the skill's SKILL.md, all stage prompts, and manifest (if present). Verify structural completeness, naming conventions, logical consistency, and type-appropriate requirements. Return findings as structured JSON.
+
+## Scan Targets
+
+Find and read:
+- `SKILL.md` — Primary structure and blueprint
+- `*.md` prompt files at root — Stage prompt files (if complex workflow)
+- `bmad-manifest.json` — Module manifest (if present)
+
+---
+
+## Part 1: SKILL.md Structure
+
+### Frontmatter (The Trigger)
+
+| Check | Why It Matters |
+|-------|----------------|
+| `name` MUST match the folder name AND follows pattern `bmad-{code}-{skillname}` or `bmad-{skillname}` | Naming convention identifies module affiliation |
+| `description` follows two-part format: [5-8 word summary]. [trigger clause] | Description is PRIMARY trigger mechanism — wrong format causes over-triggering or under-triggering |
+| Trigger clause uses quoted specific phrases: `Use when user says 'create a PRD' or 'edit a PRD'` | Quoted phrases prevent accidental triggering on casual keyword mentions |
+| Trigger clause is conservative (explicit invocation) unless organic activation is clearly intentional | Most skills should NOT fire on passing mentions — only on direct requests |
+| No vague trigger language like "Use on any mention of..." or "Helps with..." | Over-broad descriptions hijack unrelated conversations |
+| No extra frontmatter fields beyond name/description | Extra fields clutter metadata, may not parse correctly |
+
+### Required Sections
+
+| Check | Why It Matters |
+|-------|----------------|
+| Has `## Overview` section | Primes AI's understanding before detailed instructions — see prompt-craft scanner for depth assessment |
+| Has role guidance (who/what executes this workflow) | Clarifies the executor's perspective without creating a full persona |
+| Has `## On Activation` with clear activation steps | Prevents confusion about what to do when invoked |
+| Sections in logical order | Scrambled sections make AI work harder to understand flow |
+
+### Optional Sections (Valid When Purposeful)
+
+Workflows may include Identity, Communication Style, or Principles sections if personality or tone serves the workflow's purpose. These are more common in agents but not restricted to them.
+
+| Check | Why It Matters |
+|-------|----------------|
+| `## Identity` section (if present) serves a purpose | Valid when personality/tone affects workflow outcomes |
+| `## Communication Style` (if present) serves a purpose | Valid when consistent tone matters for the workflow |
+| `## Principles` (if present) serves a purpose | Valid when guiding values improve workflow outcomes |
+| **NO `## On Exit` or `## Exiting` section** | There are NO exit hooks in the system — this section would never run |
+
+### Language & Directness
+
+| Check | Why It Matters |
+|-------|----------------|
+| No "you should" or "please" language | Direct commands work better than polite requests |
+| No over-specification of obvious things | Wastes tokens, AI already knows basics |
+| Instructions address the AI directly | "When activated, this workflow..." is meta — better: "When activated, load config..." |
+| No ambiguous phrasing like "handle appropriately" | AI doesn't know what "appropriate" means without specifics |
+
+### Template Artifacts (Incomplete Build Detection)
+
+| Check | Why It Matters |
+|-------|----------------|
+| No orphaned `{if-complex-workflow}` conditionals | Orphaned conditional means build process incomplete |
+| No orphaned `{if-simple-workflow}` conditionals | Should have been resolved during skill creation |
+| No orphaned `{if-simple-utility}` conditionals | Should have been resolved during skill creation |
+| No bare placeholders like `{displayName}`, `{skillName}` | Should have been replaced with actual values |
+| No other template fragments (`{if-module}`, `{if-headless}`, etc.) | Conditional blocks should be removed, not left as text |
+| Variables from `bmad-init` are OK | `{user_name}`, `{communication_language}`, `{document_output_language}` are intentional runtime variables |
+
+### Config Integration
+
+| Check | Why It Matters |
+|-------|----------------|
+| bmad-init config loading present in On Activation | Config provides user preferences, language settings, project context |
+| Config values used where appropriate | Hardcoded values that should come from config cause inflexibility |
+
+---
+
+## Part 2: Workflow Type Detection & Type-Specific Checks
+
+Determine workflow type from SKILL.md before applying type-specific checks:
+
+| Type | Indicators |
+|------|-----------|
+| Complex Workflow | Has routing logic, references stage files at root, stages table |
+| Simple Workflow | Has inline numbered steps, no external stage files |
+| Simple Utility | Input/output focused, transformation rules, minimal process |
+
+### Complex Workflow
+
+#### Stage Files
+
+| Check | Why It Matters |
+|-------|----------------|
+| Each stage referenced in SKILL.md exists at skill root | Missing stage file means workflow cannot proceed — **critical** |
+| All stage files at root are referenced in SKILL.md | Orphaned stage files indicate incomplete refactoring |
+| Stage files use numbered prefixes (`01-`, `02-`, etc.) | Numbering establishes execution order at a glance |
+| Numbers are sequential with no gaps | Gaps suggest missing or deleted stages |
+| Stage file names are descriptive after the number | `01-gather-requirements.md` is clear; `01-step.md` is not |
+
+#### Progression Conditions
+
+| Check | Why It Matters |
+|-------|----------------|
+| Each stage prompt has explicit progression conditions | Without conditions, AI doesn't know when to advance — **critical** |
+| Progression conditions are specific and testable | "When ready" is vague; "When all 5 fields are populated" is testable |
+| Final stage has completion/output criteria | Workflow needs a defined end state |
+| No circular stage references without exit conditions | Infinite loops break workflow execution |
+
+#### Manifest (If Module-Based)
+
+| Check | Why It Matters |
+|-------|----------------|
+| `bmad-manifest.json` exists if SKILL.md references modules | Missing manifest means module loading fails |
+| Manifest lists all stage prompts | Incomplete manifest means stages can't be discovered |
+| Manifest stage names match actual filenames | Mismatches cause load failures |
+
+#### Config Headers in Stage Prompts
+
+| Check | Why It Matters |
+|-------|----------------|
+| Each stage prompt has config header specifying Language | AI needs to know what language to communicate in |
+| Stage prompts that create documents specify Output Language | Document language may differ from communication language |
+| Config header uses bmad-init variables correctly | `{communication_language}`, `{document_output_language}` |
+
+### Simple Workflow
+
+| Check | Why It Matters |
+|-------|----------------|
+| Steps are numbered sequentially | Clear execution order prevents confusion |
+| Each step has a clear action | Vague steps produce unreliable behavior |
+| Steps have defined outputs or state changes | AI needs to know what each step produces |
+| Final step has clear completion criteria | Workflow needs a defined end state |
+| No references to external stage files | Simple workflows should be self-contained inline |
+
+### Simple Utility
+
+| Check | Why It Matters |
+|-------|----------------|
+| Input format is clearly defined | AI needs to know what it receives |
+| Output format is clearly defined | AI needs to know what to produce |
+| Transformation rules are explicit | Ambiguous transformations produce inconsistent results |
+| Edge cases for input are addressed | Unexpected input causes failures |
+| No unnecessary process steps | Utilities should be direct: input → transform → output |
+
+### Headless Mode (If Declared)
+
+| Check | Why It Matters |
+|-------|----------------|
+| Headless mode setup is defined if SKILL.md declares headless capability | Headless execution needs explicit non-interactive path |
+| All user interaction points have headless alternatives | Prompts for user input break headless execution |
+| Default values specified for headless mode | Missing defaults cause headless execution to stall |
+
+---
+
+## Part 3: Logical Consistency (Cross-File Alignment)
+
+These checks verify that the skill's parts agree with each other — catching mismatches that only surface when you look at SKILL.md and its implementation together.
+
+| Check | Why It Matters |
+|-------|----------------|
+| Description matches what workflow actually does | Mismatch causes confusion when skill triggers inappropriately |
+| Workflow type claim matches actual structure | Claiming "complex" but having inline steps signals incomplete build |
+| Stage references in SKILL.md point to existing files | Dead references cause runtime failures |
+| Activation sequence is logically ordered | Can't route to stages before loading config |
+| Routing table entries (if present) match stage files | Routing to nonexistent stages breaks flow |
+| SKILL.md type-appropriate sections match detected type | Missing routing logic for complex, or unnecessary stage refs for simple |
+
+---
+
+## Severity Guidelines
+
+| Severity | When to Apply |
+|----------|---------------|
+| **Critical** | Missing stage files, missing progression conditions, circular dependencies without exit, broken references |
+| **High** | Missing On Activation, vague/missing description, orphaned template artifacts, type mismatch |
+| **Medium** | Naming convention violations, minor config issues, ambiguous language, orphaned stage files |
+| **Low** | Style preferences, ordering suggestions, minor directness improvements |
+
+---
+
+## Output Format
+
+You will receive `{skill-path}` and `{quality-report-dir}` as inputs.
+
+Write JSON findings to: `{quality-report-dir}/workflow-integrity-temp.json`
+
+Output your findings using the universal schema defined in `references/universal-scan-schema.md`.
+
+Use EXACTLY these field names: `file`, `line`, `severity`, `category`, `title`, `detail`, `action`. Do not rename, restructure, or add fields to findings.
+
+**Field mapping for this scanner:**
+- `title` — Brief description of the issue (was `issue`)
+- `detail` — Why this is a problem (was `rationale`)
+- `action` — Specific action to resolve (was `fix`)
+
+```json
+{
+  "scanner": "workflow-integrity",
+  "skill_path": "{path}",
+  "findings": [
+    {
+      "file": "SKILL.md",
+      "line": 42,
+      "severity": "critical",
+      "category": "progression",
+      "title": "Stage 03 has no progression conditions",
+      "detail": "Without explicit conditions, the AI does not know when to advance to the next stage, causing stalls or premature transitions.",
+      "action": "Add progression conditions: 'Advance when all required fields are populated and user confirms.'"
+    }
+  ],
+  "assessments": {
+    "workflow_type": "complex|simple-workflow|simple-utility",
+    "stage_summary": {
+      "total_stages": 0,
+      "missing_stages": [],
+      "orphaned_stages": [],
+      "stages_without_progression": [],
+      "stages_without_config_header": []
+    }
+  },
+  "summary": {
+    "total_findings": 0,
+    "by_severity": {"critical": 0, "high": 0, "medium": 0, "low": 0},
+    "assessment": "Brief 1-2 sentence overall assessment of workflow integrity"
+  }
+}
+```
+
+Before writing output, verify: Is your array called `findings`? Does every item have `title`, `detail`, `action`? Is `assessments` an object, not items in the findings array?
+
+## Process
+
+1. **Parallel read batch:** Read SKILL.md, bmad-manifest.json (if present), and list all `.md` files at skill root — in a single parallel batch
+2. Validate frontmatter, sections, language, template artifacts from SKILL.md
+3. Determine workflow type (complex, simple workflow, simple utility)
+4. For complex workflows: **parallel read batch** — read all stage prompt files identified in step 1
+5. For complex workflows: cross-reference stage files with SKILL.md references, check progression conditions, config headers, naming
+6. For simple workflows: verify inline steps are numbered, clear, and complete
+7. For simple utilities: verify input/output format and transformation rules
+8. Check headless mode if declared
+9. Run logical consistency checks across all files read
+10. Write JSON to `{quality-report-dir}/workflow-integrity-temp.json`
+11. Return only the filename: `workflow-integrity-temp.json`
+
+## Critical After Draft Output
+
+**Before finalizing, think one level deeper and verify completeness and quality:**
+
+### Scan Completeness
+- Did I read the entire SKILL.md file?
+- Did I correctly identify the workflow type?
+- Did I read ALL stage files at skill root (for complex workflows)?
+- Did I verify every stage reference in SKILL.md has a corresponding file?
+- Did I check progression conditions in every stage prompt?
+- Did I check config headers in stage prompts?
+- Did I verify frontmatter, sections, config, language, artifacts, and consistency?
+
+### Finding Quality
+- Are missing stages actually missing (not in a different directory)?
+- Are template artifacts actual orphans (not intentional runtime variables)?
+- Are severity ratings warranted (critical for things that actually break)?
+- Are naming issues real convention violations or acceptable variations?
+- Are progression condition issues genuine (vague conditions vs. intentionally flexible)?
+- Are "invalid-section" findings truly invalid (e.g., On Exit which has no system hook)?
+
+### Cross-File Consistency
+- Do SKILL.md references and actual files agree?
+- Does the declared workflow type match the actual structure?
+- Does the stage_summary accurately reflect the workflow's state?
+- Would fixing critical issues resolve the structural problems?
+
+Only after this verification, write final JSON and return filename.

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

@@ -0,0 +1,61 @@
+# 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. May opt out of bmad-init for true standalone use. | Single SKILL.md + scripts/ | Composable building block with clear input/output, single-purpose |
+| **Simple Workflow** | Multi-step process contained in a single SKILL.md. Uses bmad-init. 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, manifest 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. Has bmad-manifest.json.
+- **Standalone:** Independent skill. Uses `bmad-{skillname}` naming.
+
+All workflows use `bmad-init` by default unless explicitly opted out (truly standalone utilities).