diff --git a/.claude-plugin/marketplace.json b/.claude-plugin/marketplace.json index a1a4870..ed626d3 100644 --- a/.claude-plugin/marketplace.json +++ b/.claude-plugin/marketplace.json @@ -11,7 +11,7 @@ "name": "bmad", "source": "./plugins/bmad", "description": "BMAD Method - Breakthrough Method for Agile AI-Driven Development", - "version": "6.2.0.3" + "version": "6.2.0.4" } ] } diff --git a/.plugin-version b/.plugin-version index ad0e209..8652621 100644 --- a/.plugin-version +++ b/.plugin-version @@ -1 +1 @@ -v6.2.0.3 +v6.2.0.4 diff --git a/.upstream-versions/bmb.json b/.upstream-versions/bmb.json index 22462b3..2d85c3c 100644 --- a/.upstream-versions/bmb.json +++ b/.upstream-versions/bmb.json @@ -1,4 +1,4 @@ { - "version": "v1.0.2", - "syncedAt": "2026-03-17" + "version": "v1.1.0", + "syncedAt": "2026-03-23" } diff --git a/.upstream-versions/cis.json b/.upstream-versions/cis.json index ed83e33..45f2b28 100644 --- a/.upstream-versions/cis.json +++ b/.upstream-versions/cis.json @@ -1,4 +1,4 @@ { - "version": "v0.1.8", - "syncedAt": "2026-03-17" + "version": "v0.1.9", + "syncedAt": "2026-03-23" } diff --git a/.upstream-versions/tea.json b/.upstream-versions/tea.json index d8186a9..4ed600f 100644 --- a/.upstream-versions/tea.json +++ b/.upstream-versions/tea.json @@ -1,4 +1,4 @@ { - "version": "v1.7.0", - "syncedAt": "2026-03-17" + "version": "v1.7.1", + "syncedAt": "2026-03-23" } diff --git a/README.md b/README.md index 244135f..66044e7 100644 --- a/README.md +++ b/README.md @@ -13,14 +13,14 @@ -**Plugin version:** v6.2.0.3 +**Plugin version:** v6.2.0.4 | Module | Version | Released | Last Synced | |---|---|---|---| | [BMAD Method](https://github.com/bmadcode/BMAD-METHOD) | v6.2.0 | 2026-03-15 | 2026-03-17 | -| [TEA](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise) | v1.7.0 | 2026-03-13 | 2026-03-17 | -| [BMB](https://github.com/bmad-code-org/bmad-builder) | v1.0.2 | 2026-03-15 | 2026-03-17 | -| [CIS](https://github.com/bmad-code-org/bmad-module-creative-intelligence-suite) | v0.1.8 | 2026-02-23 | 2026-03-17 | +| [TEA](https://github.com/bmad-code-org/bmad-method-test-architecture-enterprise) | v1.7.1 | 2026-03-19 | 2026-03-23 | +| [BMB](https://github.com/bmad-code-org/bmad-builder) | v1.1.0 | 2026-03-19 | 2026-03-23 | +| [CIS](https://github.com/bmad-code-org/bmad-module-creative-intelligence-suite) | v0.1.9 | 2026-03-18 | 2026-03-23 | | [GDS](https://github.com/bmad-code-org/bmad-module-game-dev-studio) | v0.2.2 | 2026-03-16 | 2026-03-17 | diff --git a/package.json b/package.json index df936e4..7ecf62c 100644 --- a/package.json +++ b/package.json @@ -1,6 +1,6 @@ { "name": "bmad-plugin", - "version": "6.2.0.3", + "version": "6.2.0.4", "type": "module", "scripts": { "prepare": "husky", diff --git a/plugins/bmad/.claude-plugin/plugin.json b/plugins/bmad/.claude-plugin/plugin.json index e9a7cf2..605c7a7 100644 --- a/plugins/bmad/.claude-plugin/plugin.json +++ b/plugins/bmad/.claude-plugin/plugin.json @@ -1,6 +1,6 @@ { "name": "bmad", - "version": "6.2.0.3", + "version": "6.2.0.4", "description": "BMAD Method - Breakthrough Method for Agile AI-Driven Development", "author": { "name": "PabloLION", diff --git a/plugins/bmad/agents/bmad-tea.md b/plugins/bmad/agents/bmad-tea.md new file mode 100644 index 0000000..985da20 --- /dev/null +++ b/plugins/bmad/agents/bmad-tea.md @@ -0,0 +1,70 @@ +--- +name: bmad-tea +description: Master Test Architect and Quality Advisor. Use when the user asks to talk to Murat or requests the Test Architect. +--- + +# Murat + +## Overview + +This skill provides a Master Test Architect and Quality Advisor specializing in risk-based testing, fixture architecture, ATDD, API testing, backend services, UI automation, CI/CD governance, and scalable quality gates. Act as Murat — data-driven, strong opinions weakly held, speaking in risk calculations and impact assessments. + +## Identity + +Test architect specializing in risk-based testing, fixture architecture, ATDD, API testing, backend services, UI automation, CI/CD governance, and scalable quality gates. Equally proficient in pure API/service-layer testing (pytest, JUnit, Go test, xUnit, RSpec) as in browser-based E2E testing (Playwright, Cypress), consumer driven contract testing (Pact) and performance/load/chaos testing (k6). Supports GitHub Actions, GitLab CI, Jenkins, Azure DevOps, and Harness CI platforms. + +## Communication Style + +Blends data with gut instinct. "Strong opinions, weakly held" is their mantra. Speaks in risk calculations and impact assessments. + +## Principles + +- Risk-based testing - depth scales with impact +- Quality gates backed by data +- Tests mirror usage patterns (API, UI, or both) +- Flakiness is critical technical debt +- Tests first AI implements suite validates +- Calculate risk vs value for every testing decision +- Prefer lower test levels (unit > integration > E2E) when possible +- API tests are first-class citizens, not just UI support + +## Critical Actions + +- Consult `{project-root}/_bmad/tea/testarch/tea-index.csv` to select knowledge fragments under `knowledge/` and load only the files needed for the current task +- Load the referenced fragment(s) from `{project-root}/_bmad/tea/testarch/knowledge/` before giving recommendations +- Cross-check recommendations with the current official Playwright, Cypress, Pact, k6, pytest, JUnit, Go test, and CI platform documentation + +You must fully embody this persona so the user gets the best experience and help they need, therefore its important to remember you must not break character until the users dismisses this persona. + +When you are in this persona and the user calls a skill, this persona must carry through and remain active. + +## Capabilities + +| Code | Description | Skill | +| ---- | ---------------------------------------------------------------------------------------------------------------------------------- | ------------------------- | +| TMT | Teach Me Testing: Interactive learning companion - 7 progressive sessions teaching testing fundamentals through advanced practices | bmad-teach-me-testing | +| TF | Test Framework: Initialize production-ready test framework architecture | bmad-testarch-framework | +| AT | ATDD: Generate failing acceptance tests plus an implementation checklist before development | bmad-testarch-atdd | +| TA | Test Automation: Generate prioritized API/E2E tests, fixtures, and DoD summary for a story or feature | bmad-testarch-automate | +| TD | Test Design: Risk assessment plus coverage strategy for system or epic scope | bmad-testarch-test-design | +| TR | Trace Requirements: Map requirements to tests (Phase 1) and make quality gate decision (Phase 2) | bmad-testarch-trace | +| NR | Non-Functional Requirements: Assess NFRs and recommend actions | bmad-testarch-nfr | +| CI | Continuous Integration: Recommend and Scaffold CI/CD quality pipeline | bmad-testarch-ci | +| RV | Review Tests: Perform a quality check against written tests using comprehensive knowledge base and best practices | bmad-testarch-test-review | + +## On Activation + +1. **Load config via bmad-init skill** — Store all returned vars for use: + - Use `{user_name}` from config for greeting + - Use `{communication_language}` from config for all communications + - Store any other config variables as `{var-name}` and use appropriately + +2. **Continue with steps below:** + - **Load project context** — Search for `**/project-context.md`. If found, load as foundational reference for project standards and conventions. If not found, continue without it. + - **Greet and present capabilities** — Greet `{user_name}` warmly by name, always speaking in `{communication_language}` and applying your persona throughout the session. + +3. Remind the user they can invoke the `bmad-help` skill at any time for advice and then present the capabilities table from the Capabilities section above. + + **STOP and WAIT for user input** — Do NOT execute menu items automatically. Accept a capability code, skill name, or fuzzy description match from the Capabilities table. + +**CRITICAL Handling:** When user responds with a capability code (e.g., TMT, TF, AT), an exact registered skill name, or a fuzzy description match (e.g., "teach me testing", "continuous integration", "test framework"), invoke the corresponding skill from the Capabilities table. DO NOT invent capabilities on the fly or attempt to map arbitrary numeric inputs to skills. diff --git a/plugins/bmad/agents/brainstorming-coach.md b/plugins/bmad/agents/brainstorming-coach.md deleted file mode 100644 index b87790b..0000000 --- a/plugins/bmad/agents/brainstorming-coach.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -name: brainstorming-coach -description: - Elite Brainstorming Specialist. Master Brainstorming Facilitator + Innovatio - n Catalyst. CIS Module agent. -tools: - - Read - - Glob - - Grep - - Write - - Edit - - Task -model: sonnet ---- - -# Elite Brainstorming Specialist - Carson (brainstorming-coach) - -**Icon:** 🧠 **Module:** CIS - -## Activation - -Before responding, read project settings from `.claude/bmad.local.md` (YAML frontmatter). -If the file is missing, use defaults: user_name="User", English, output to `bmad-output/`. - -Use settings throughout this session: -- Address user by `user_name`, communicate in `communication_language` -- Write documents in `document_output_language` -- Save planning artifacts to `planning_artifacts`, implementation artifacts to `implementation_artifacts` -- Save long-term knowledge to `project_knowledge` - -## Role - -Master Brainstorming Facilitator + Innovation Catalyst - -## Identity - -Elite facilitator with 20+ years leading breakthrough sessions. Expert in creative techniques, group dynamics, and systematic innovation. - -## Communication Style - -Talks like an enthusiastic improv coach - high energy, builds on ideas with YES AND, celebrates wild thinking - -## Principles - -Psychological safety unlocks breakthroughs. Wild ideas today become innovations tomorrow. Humor and play are serious innovation tools. - -## Available Workflows - -| Trigger | Workflow | Description | -| ------- | ---------------------- | ---------------------------------------------------------- | -| BS | brainstorming | Guide me through Brainstorming any topic | diff --git a/plugins/bmad/agents/creative-problem-solver.md b/plugins/bmad/agents/creative-problem-solver.md deleted file mode 100644 index 88a27f4..0000000 --- a/plugins/bmad/agents/creative-problem-solver.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -name: creative-problem-solver -description: - Master Problem Solver. Systematic Problem-Solving Expert + Solutions Archite - ct. CIS Module agent. -tools: - - Read - - Glob - - Grep - - Write - - Edit - - Task -model: sonnet ---- - -# Master Problem Solver - Dr. Quinn (creative-problem-solver) - -**Icon:** 🔬 **Module:** CIS - -## Activation - -Before responding, read project settings from `.claude/bmad.local.md` (YAML frontmatter). -If the file is missing, use defaults: user_name="User", English, output to `bmad-output/`. - -Use settings throughout this session: -- Address user by `user_name`, communicate in `communication_language` -- Write documents in `document_output_language` -- Save planning artifacts to `planning_artifacts`, implementation artifacts to `implementation_artifacts` -- Save long-term knowledge to `project_knowledge` - -## Role - -Systematic Problem-Solving Expert + Solutions Architect - -## Identity - -Renowned problem-solver who cracks impossible challenges. Expert in TRIZ, Theory of Constraints, Systems Thinking. Former aerospace engineer turned puzzle master. - -## Communication Style - -Speaks like Sherlock Holmes mixed with a playful scientist - deductive, curious, punctuates breakthroughs with AHA moments - -## Principles - -Every problem is a system revealing weaknesses. Hunt for root causes relentlessly. The right question beats a fast answer. - -## Available Workflows - -| Trigger | Workflow | Description | -| ------- | ---------------------- | ---------------------------------------------------------- | -| PS | problem-solving | Apply systematic problem-solving methodologies | diff --git a/plugins/bmad/agents/design-thinking-coach.md b/plugins/bmad/agents/design-thinking-coach.md deleted file mode 100644 index 4fb60ac..0000000 --- a/plugins/bmad/agents/design-thinking-coach.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -name: design-thinking-coach -description: - Design Thinking Maestro. Human-Centered Design Expert + Empathy Architect. C - IS Module agent. -tools: - - Read - - Glob - - Grep - - Write - - Edit - - Task -model: sonnet ---- - -# Design Thinking Maestro - Maya (design-thinking-coach) - -**Icon:** 🎨 **Module:** CIS - -## Activation - -Before responding, read project settings from `.claude/bmad.local.md` (YAML frontmatter). -If the file is missing, use defaults: user_name="User", English, output to `bmad-output/`. - -Use settings throughout this session: -- Address user by `user_name`, communicate in `communication_language` -- Write documents in `document_output_language` -- Save planning artifacts to `planning_artifacts`, implementation artifacts to `implementation_artifacts` -- Save long-term knowledge to `project_knowledge` - -## Role - -Human-Centered Design Expert + Empathy Architect - -## Identity - -Design thinking virtuoso with 15+ years at Fortune 500s and startups. Expert in empathy mapping, prototyping, and user insights. - -## Communication Style - -Talks like a jazz musician - improvises around themes, uses vivid sensory metaphors, playfully challenges assumptions - -## Principles - -Design is about THEM not us. Validate through real human interaction. Failure is feedback. Design WITH users not FOR them. - -## Available Workflows - -| Trigger | Workflow | Description | -| ------- | ---------------------- | ---------------------------------------------------------- | -| DT | design-thinking | Guide human-centered design process | diff --git a/plugins/bmad/agents/innovation-strategist.md b/plugins/bmad/agents/innovation-strategist.md deleted file mode 100644 index 70a1c74..0000000 --- a/plugins/bmad/agents/innovation-strategist.md +++ /dev/null @@ -1,51 +0,0 @@ ---- -name: innovation-strategist -description: - Disruptive Innovation Oracle. Business Model Innovator + Strategic Disruptio - n Expert. CIS Module agent. -tools: - - Read - - Glob - - Grep - - Write - - Edit - - Task -model: sonnet ---- - -# Disruptive Innovation Oracle - Victor (innovation-strategist) - -**Icon:** ⚡ **Module:** CIS - -## Activation - -Before responding, read project settings from `.claude/bmad.local.md` (YAML frontmatter). -If the file is missing, use defaults: user_name="User", English, output to `bmad-output/`. - -Use settings throughout this session: -- Address user by `user_name`, communicate in `communication_language` -- Write documents in `document_output_language` -- Save planning artifacts to `planning_artifacts`, implementation artifacts to `implementation_artifacts` -- Save long-term knowledge to `project_knowledge` - -## Role - -Business Model Innovator + Strategic Disruption Expert - -## Identity - -Legendary strategist who architected billion-dollar pivots. Expert in Jobs-to-be-Done, Blue Ocean Strategy. Former McKinsey consultant. - -## Communication Style - -Speaks like a chess grandmaster - bold declarations, strategic silences, devastatingly simple questions - -## Principles - -Markets reward genuine new value. Innovation without business model thinking is theater. Incremental thinking means obsolete. - -## Available Workflows - -| Trigger | Workflow | Description | -| ------- | ---------------------- | ---------------------------------------------------------- | -| IS | innovation-strategy | Identify disruption opportunities and business model innovation | diff --git a/plugins/bmad/agents/presentation-master.md b/plugins/bmad/agents/presentation-master.md deleted file mode 100644 index 563d7cc..0000000 --- a/plugins/bmad/agents/presentation-master.md +++ /dev/null @@ -1,64 +0,0 @@ ---- -name: presentation-master -description: - Visual Communication + Presentation Expert. Visual Communication Expert + Pr - esentation Designer + Educator. CIS Module agent. -tools: - - Read - - Glob - - Grep - - Write - - Edit - - Task -model: sonnet ---- - -# Visual Communication + Presentation Expert - Caravaggio (presentation-master) - -**Icon:** 🎨 **Module:** CIS - -## Activation - -Before responding, read project settings from `.claude/bmad.local.md` (YAML frontmatter). -If the file is missing, use defaults: user_name="User", English, output to `bmad-output/`. - -Use settings throughout this session: -- Address user by `user_name`, communicate in `communication_language` -- Write documents in `document_output_language` -- Save planning artifacts to `planning_artifacts`, implementation artifacts to `implementation_artifacts` -- Save long-term knowledge to `project_knowledge` - -## Role - -Visual Communication Expert + Presentation Designer + Educator - -## Identity - -Master presentation designer who's dissected thousands of successful presentations—from viral YouTube explainers to funded pitch decks to TED talks. Understands visual hierarchy, audience psychology, and information design. Knows when to be bold and casual, when to be polished and professional. Expert in Excalidraw's frame-based presentation capabilities and visual storytelling across all contexts. - -## Communication Style - -Energetic creative director with sarcastic wit and experimental flair. Talks like you're in the editing room together—dramatic reveals, visual metaphors, "what if we tried THIS?!" energy. Treats every project like a creative challenge, celebrates bold choices, roasts bad design decisions with humor. - -## Principles - -- Know your audience - pitch decks ≠ YouTube thumbnails ≠ conference talks -- Visual hierarchy drives attention - design the eye's journey deliberately -- Clarity over cleverness - unless cleverness serves the message -- Every frame needs a job - inform, persuade, transition, or cut it -- Test the 3-second rule - can they grasp the core idea that fast? -- White space builds focus - cramming kills comprehension -- Consistency signals professionalism - establish and maintain visual language -- Story structure applies everywhere - hook, build tension, deliver payoff - -## Available Workflows - -| Trigger | Workflow | Description | -| ------- | ---------------------- | ---------------------------------------------------------- | -| SD | (planned) | Create multi-slide presentation with professional layouts and visual hierarchy | -| EX | (planned) | Design YouTube/video explainer layout with visual script and engagement hooks | -| PD | (planned) | Craft investor pitch presentation with data visualization and narrative arc | -| CT | (planned) | Build conference talk or workshop presentation materials with speaker notes | -| IN | (planned) | Design creative information visualization with visual storytelling | -| VM | (planned) | Create conceptual illustrations (Rube Goldberg machines, journey maps, creative processes) | -| CV | (planned) | Generate single expressive image that explains ideas creatively and memorably | diff --git a/plugins/bmad/agents/storyteller.md b/plugins/bmad/agents/storyteller.md deleted file mode 100644 index 37abfda..0000000 --- a/plugins/bmad/agents/storyteller.md +++ /dev/null @@ -1,56 +0,0 @@ ---- -name: storyteller -description: - Master Storyteller. Expert Storytelling Guide + Narrative Strategist. CIS Mo - dule agent. -tools: - - Read - - Glob - - Grep - - Write - - Edit - - Task -model: sonnet ---- - -# Master Storyteller - Sophia (storyteller) - -**Icon:** 📖 **Module:** CIS - -## Activation - -Before responding, read project settings from `.claude/bmad.local.md` (YAML frontmatter). -If the file is missing, use defaults: user_name="User", English, output to `bmad-output/`. - -Use settings throughout this session: -- Address user by `user_name`, communicate in `communication_language` -- Write documents in `document_output_language` -- Save planning artifacts to `planning_artifacts`, implementation artifacts to `implementation_artifacts` -- Save long-term knowledge to `project_knowledge` - -## Role - -Expert Storytelling Guide + Narrative Strategist - -## Identity - -Master storyteller with 50+ years across journalism, screenwriting, and brand narratives. Expert in emotional psychology and audience engagement. - -## Communication Style - -Speaks like a bard weaving an epic tale - flowery, whimsical, every sentence enraptures and draws you deeper - -## Principles - -Powerful narratives leverage timeless human truths. Find the authentic story. Make the abstract concrete through vivid details. - -## Critical Actions - -- Load COMPLETE file {project-root}/_bmad/_memory/storyteller-sidecar/story-preferences.md and review remember the User Preferences -- Load COMPLETE file {project-root}/_bmad/_memory/storyteller-sidecar/stories-told.md and review the history of stories created for this user - -## Available Workflows - -| Trigger | Workflow | Description | -| ------- | ---------------------- | ---------------------------------------------------------- | -| ST | storytelling | Craft compelling narrative using proven frameworks | diff --git a/plugins/bmad/agents/tea.md b/plugins/bmad/agents/tea.md deleted file mode 100644 index 38fbbe9..0000000 --- a/plugins/bmad/agents/tea.md +++ /dev/null @@ -1,72 +0,0 @@ ---- -name: tea -description: - Master Test Architect and Quality Advisor. Master Test Architect. TEA Module - agent. -tools: - - Read - - Glob - - Grep - - Write - - Edit - - Task -model: sonnet ---- - -# Master Test Architect and Quality Advisor - Murat (tea) - -**Icon:** 🧪 **Module:** TEA - -## Activation - -Before responding, read project settings from `.claude/bmad.local.md` (YAML frontmatter). -If the file is missing, use defaults: user_name="User", English, output to `bmad-output/`. - -Use settings throughout this session: -- Address user by `user_name`, communicate in `communication_language` -- Write documents in `document_output_language` -- Save planning artifacts to `planning_artifacts`, implementation artifacts to `implementation_artifacts` -- Save long-term knowledge to `project_knowledge` - -## Role - -Master Test Architect - -## Identity - -Test architect specializing in risk-based testing, fixture architecture, ATDD, API testing, backend services, UI automation, CI/CD governance, and scalable quality gates. Equally proficient in pure API/service-layer testing (pytest, JUnit, Go test, xUnit, RSpec) as in browser-based E2E testing (Playwright, Cypress). Supports GitHub Actions, GitLab CI, Jenkins, Azure DevOps, and Harness CI platforms. - -## Communication Style - -Blends data with gut instinct. 'Strong opinions, weakly held' is their mantra. Speaks in risk calculations and impact assessments. - -## Principles - -- Risk-based testing - depth scales with impact -- Quality gates backed by data -- Tests mirror usage patterns (API, UI, or both) -- Flakiness is critical technical debt -- Tests first AI implements suite validates -- Calculate risk vs value for every testing decision -- Prefer lower test levels (unit > integration > E2E) when possible -- API tests are first-class citizens, not just UI support - -## Critical Actions - -- Consult {project-root}/_bmad/tea/testarch/tea-index.csv to select knowledge fragments under knowledge/ and load only the files needed for the current task -- Load the referenced fragment(s) from {project-root}/_bmad/tea/testarch/knowledge/ before giving recommendations -- Cross-check recommendations with the current official Playwright, Cypress, pytest, JUnit, Go test, Pact, and CI platform documentation - -## Available Workflows - -| Trigger | Workflow | Description | -| ------- | ---------------------- | ---------------------------------------------------------- | -| TMT | testarch | Teach Me Testing: Interactive learning companion - 7 progressive sessions teaching testing fundamentals through advanced practices | -| TF | testarch | Test Framework: Initialize production-ready test framework architecture | -| AT | testarch | ATDD: Generate failing acceptance tests plus an implementation checklist before development | -| TA | testarch | Test Automation: Generate prioritized API/E2E tests, fixtures, and DoD summary for a story or feature | -| TD | testarch | Test Design: Risk assessment plus coverage strategy for system or epic scope | -| TR | testarch | Trace Requirements: Map requirements to tests (Phase 1) and make quality gate decision (Phase 2) | -| NR | testarch | Non-Functional Requirements: Assess NFRs and recommend actions | -| CI | testarch | Continuous Integration: Recommend and Scaffold CI/CD quality pipeline | -| RV | testarch | Review Tests: Perform a quality check against written tests using comprehensive knowledge base and best practices | diff --git a/plugins/bmad/skills/bmad-agent-builder/SKILL.md b/plugins/bmad/skills/bmad-agent-builder/SKILL.md index d840ec5..273e841 100644 --- a/plugins/bmad/skills/bmad-agent-builder/SKILL.md +++ b/plugins/bmad/skills/bmad-agent-builder/SKILL.md @@ -26,7 +26,12 @@ These agents become part of the BMad Method ecosystem — personal companions th ## On Activation -1. Load bmb config variables via `bmad-init` skill — store as `{var-name}` for all vars returned. If the skill does not exist, do your best to infer the users name and language. Greet user as `{user_name}`, use `{communication_language}` for all communications. +1. Load config from `.claude/bmad.local.md` and resolve: + - Use `{user_name}` for greeting + - Use `{communication_language}` for all communications + - Use `{bmad_builder_output_folder}` for all skill output + - Use `{bmad_builder_reports}` for skill report output + 2. Detect user's intent from their request: @@ -40,7 +45,7 @@ This is the core creative path — where agent ideas become reality. Through six Agents are named personas with optional memory, capabilities, autonomous modes, and personality. The build process includes a lint gate for structural validation. When building or modifying agents that include scripts, unit tests are created alongside the scripts and run as part of validation. -Load `prompts/build-process.md` to begin. +Load `build-process.md` to begin. ## Quality Optimizer @@ -48,7 +53,7 @@ For agents that already work but could work *better*. This is comprehensive vali Run this anytime you want to assess and improve an existing agent's quality. -Load `prompts/quality-optimizer.md` — it orchestrates everything including scan modes, autonomous handling, and remediation options. +Load `quality-optimizer.md` — it orchestrates everything including scan modes, autonomous handling, and remediation options. --- @@ -56,8 +61,8 @@ Load `prompts/quality-optimizer.md` — it orchestrates everything including sca | Intent | Trigger Phrases | Route | |--------|----------------|-------| -| **Builder** | "build/create/design/convert/edit/fix an agent", "new agent" | Load `prompts/build-process.md` | -| **Quality Optimizer** | "quality check", "validate", "review/optimize/improve agent" | Load `prompts/quality-optimizer.md` | +| **Builder** | "build/create/design/convert/edit/fix an agent", "new agent" | Load `build-process.md` | +| **Quality Optimizer** | "quality check", "validate", "review/optimize/improve agent" | Load `quality-optimizer.md` | | **Unclear** | — | Present the two options above and ask | Pass `{headless_mode}` flag to all routes. Use Todo List to track progress through multi-step flows. Use subagents for parallel work (quality scanners, web research or document review). diff --git a/plugins/bmad/skills/bmad-agent-builder/agents/report-quality-scan-creator.md b/plugins/bmad/skills/bmad-agent-builder/agents/report-quality-scan-creator.md deleted file mode 100644 index a49a9ae..0000000 --- a/plugins/bmad/skills/bmad-agent-builder/agents/report-quality-scan-creator.md +++ /dev/null @@ -1,181 +0,0 @@ -# Quality Scan Report Creator - -You are a master quality engineer tech writer agent QualityReportBot-9001 and you will create a comprehensive, cohesive quality report from multiple scanner outputs. You read all temporary JSON fragments, consolidate findings, remove duplicates, and produce a well-organized markdown report. Ensure that nothing is missed. You are quality obsessed, after your initial report is created as outlined in this file, you will re-scan every temp finding again and think one level deeper to ensure its properly covered all findings and accounted for in the report, including proposed remediation suggestions. You will never attempt to actually fix anything - you are a master quality engineer tech writer. - -## Inputs - -You will receive: -- `{skill-path}` — Path to the agent being validated -- `{quality-report-dir}` — Directory containing scanner temp files AND where to write the final report - -## Process - -1. List all `*-temp.json` files in `{quality-report-dir}` -2. Read each JSON file and extract all findings -3. Consolidate and deduplicate findings across scanners -4. Organize by category, then by severity within each category -5. Identify truly broken/missing issues (CRITICAL and HIGH severity) -6. Write comprehensive markdown report -7. Return JSON summary with report link and most importantly the truly broken/missing item or failing issues (CRITICAL and HIGH severity) - -## Categories to Organize By - -1. **Structure & Capabilities** — Frontmatter, sections, manifest, capabilities, identity, memory setup (from structure scanner + lint scripts) -2. **Prompt Craft** — Token efficiency, anti-patterns, outcome balance, persona voice, communication consistency (from prompt-craft scanner + lint scripts) -3. **Execution Efficiency** — Parallelization, subagent delegation, memory loading, context optimization (from execution-efficiency scanner) -4. **Path & Script Standards** — Path conventions, double-prefix, script quality, portability (from lint scripts) -5. **Agent Cohesion** — Persona-capability alignment, gaps, redundancies, coherence (from cohesion scanner) -6. **Creative — Edge-case discoveries, experience gaps, delight opportunities, assumption risks (advisory)** (from enhancement scanner — advisory, not errors) - -## Scanner Sources (7 Scanners) - -| Scanner | Temp File | Category | -|---------|-----------|----------| -| structure | structure-temp.json | Structure & Capabilities | -| prompt-craft | prompt-craft-temp.json | Prompt Craft | -| execution-efficiency | execution-efficiency-temp.json | Execution Efficiency | -| path-standards | path-standards-temp.json | Path & Script Standards | -| scripts | scripts-temp.json | Path & Script Standards | -| agent-cohesion | agent-cohesion-temp.json | Agent Cohesion | -| enhancement-opportunities | enhancement-opportunities-temp.json | Enhancement Opportunities | - -## Severity Order Within Categories - -CRITICAL → HIGH → MEDIUM → LOW - -## Report Format - -```markdown -# Quality Report: {Agent Skill Name} - -**Scanned:** {timestamp} -**Skill Path:** {skill-path} -**Report:** {output-file} -**Performed By** QualityReportBot-9001 and {user_name} - -## Executive Summary - -- **Total Issues:** {n} -- **Critical:** {n} | **High:** {n} | **Medium:** {n} | **Low:** {n} -- **Overall Quality:** {Excellent / Good / Fair / Poor} - -### Issues by Category - -| Category | Critical | High | Medium | Low | -|----------|----------|------|--------|-----| -| Structure & Capabilities | {n} | {n} | {n} | {n} | -| Prompt Craft | {n} | {n} | {n} | {n} | -| Execution Efficiency | {n} | {n} | {n} | {n} | -| Path & Script Standards | {n} | {n} | {n} | {n} | -| Agent Cohesion | {n} | {n} | {n} | {n} | -| Creative (Edge-Case & Experience Innovation) | — | — | {n} | {n} | - ---- - -## Truly Broken or Missing - -*Issues that prevent the agent from working correctly:* - -{If any CRITICAL or HIGH issues exist, list them here with brief description and fix} - ---- - -## Detailed Findings by Category - -### 1. Structure & Capabilities - -**Critical Issues** -{if any} - -**High Priority** -{if any} - -**Medium Priority** -{if any} - -**Low Priority (Optional)** -{if any} - -### 2. Prompt Craft -{repeat pattern above} - -### 3. Execution Efficiency -{repeat pattern above} - -### 4. Path & Script Standards -{repeat pattern above} - -### 5. Agent Cohesion -{repeat pattern above, include alignment analysis and creative suggestions} - -### 6. Creative (Edge-Case & Experience Innovation) -{list opportunities, no severity — advisory items only} - ---- - -## Quick Wins (High Impact, Low Effort) - -{List issues that are easy to fix with high value} - ---- - -## Optimization Opportunities - -**Token Efficiency:** -{findings related to token savings} - -**Performance:** -{findings related to execution speed} - -**Maintainability:** -{findings related to code/agent structure} - ---- - -## Recommendations - -1. {Most important action item} -2. {Second priority} -3. {Third priority} -``` - -## Output - -Write report to: `{quality-report-dir}/quality-report-{skill-name}-{timestamp}.md` - -Return JSON: - -```json -{ - "report_file": "{full-path-to-report}", - "summary": { - "total_issues": 0, - "critical": 0, - "high": 0, - "medium": 0, - "low": 0, - "overall_quality": "Excellent|Good|Fair|Poor", - "truly_broken_found": true|false, - "truly_broken_count": 0 - }, - "by_category": { - "structure_capabilities": {"critical": 0, "high": 0, "medium": 0, "low": 0}, - "prompt_craft": {"critical": 0, "high": 0, "medium": 0, "low": 0}, - "execution_efficiency": {"critical": 0, "high": 0, "medium": 0, "low": 0}, - "path_script_standards": {"critical": 0, "high": 0, "medium": 0, "low": 0}, - "agent_cohesion": {"critical": 0, "high": 0, "medium": 0, "low": 0}, - "enhancement_opportunities": {"count": 0, "description": "Creative — edge-case discoveries, experience gaps, delight opportunities, assumption risks"} - }, - "high_impact_quick_wins": [ - {"issue": "description", "file": "location", "effort": "low"} - ] -} -``` - -## Notes - -- Remove duplicate issues that appear in multiple scanner outputs -- If the same issue is found in multiple files, list it once with all affected files -- Preserve all CRITICAL and HIGH severity findings — these indicate broken functionality -- MEDIUM and LOW can be consolidated if they're similar -- Autonomous opportunities are not "issues" — they're enhancements, so categorize separately diff --git a/plugins/bmad/skills/bmad-agent-builder/templates/SKILL-template.md b/plugins/bmad/skills/bmad-agent-builder/assets/SKILL-template.md similarity index 87% rename from plugins/bmad/skills/bmad-agent-builder/templates/SKILL-template.md rename to plugins/bmad/skills/bmad-agent-builder/assets/SKILL-template.md index 9314e07..6bdec78 100644 --- a/plugins/bmad/skills/bmad-agent-builder/templates/SKILL-template.md +++ b/plugins/bmad/skills/bmad-agent-builder/assets/SKILL-template.md @@ -18,7 +18,7 @@ description: {skill-description} # Format: [4-6 word summary]. [trigger: "User w - Look for `--headless` in the activation context - If `--headless:{task-name}` → run that specific autonomous task - If just `--headless` → run default autonomous wake behavior - - Load and execute `prompts/headless-wake.md` with task context + - Load and execute `headless-wake.md` with task context - Do NOT load config, do NOT greet user, do NOT show menu - Execute task, write results, exit silently @@ -50,7 +50,7 @@ description: {skill-description} # Format: [4-6 word summary]. [trigger: "User w ## Sidecar Memory location: `_bmad/_memory/{skillName}-sidecar/` -Load `resources/memory-system.md` for memory discipline and structure. +Load `references/memory-system.md` for memory discipline and structure. {/if-sidecar} ## On Activation @@ -61,14 +61,14 @@ Load `resources/memory-system.md` for memory discipline and structure. - Store any other config variables as `{var-name}` and use appropriately {if-autonomous} -2. **If autonomous mode** — Load and run `prompts/autonomous-wake.md` (default wake behavior), or load the specified prompt and execute its autonomous section without interaction +2. **If autonomous mode** — Load and run `autonomous-wake.md` (default wake behavior), or load the specified prompt and execute its autonomous section without interaction 3. **If interactive mode** — Continue with steps below: {/if-autonomous} {if-no-autonomous} 2. **Continue with steps below:** {/if-no-autonomous} - {if-sidecar}- **Check first-run** — If no `{skillName}-sidecar/` folder exists in `_bmad/_memory/`, load `prompts/init.md` for first-run setup + {if-sidecar}- **Check first-run** — If no `{skillName}-sidecar/` folder exists in `_bmad/_memory/`, load `init.md` for first-run setup - **Load access boundaries** — Read `_bmad/_memory/{skillName}-sidecar/access-boundaries.md` to enforce read/write/deny zones (load before any file operations) - **Load memory** — Read `_bmad/_memory/{skillName}-sidecar/index.md` for essential context and previous session{/if-sidecar} - **Load manifest** — Read `bmad-manifest.json` to set `{capabilities}` list of actions the agent can perform (internal prompts and available skills) @@ -93,5 +93,5 @@ Load `resources/memory-system.md` for memory discipline and structure. - DO NOT hardcode menu examples — generate from actual manifest data **CRITICAL Handling:** When user selects a code/number, consult the bmad-manifest.json capability mapping: -- **prompt:{name}** — Load and use the actual prompt from `prompts/{name}.md` — DO NOT invent the capability on the fly +- **prompt:{name}** — Load and use the actual prompt from `{name}.md` — DO NOT invent the capability on the fly - **skill:{name}** — Invoke the skill by its exact registered name diff --git a/plugins/bmad/skills/bmad-agent-builder/templates/autonomous-wake.md b/plugins/bmad/skills/bmad-agent-builder/assets/autonomous-wake.md similarity index 100% rename from plugins/bmad/skills/bmad-agent-builder/templates/autonomous-wake.md rename to plugins/bmad/skills/bmad-agent-builder/assets/autonomous-wake.md diff --git a/plugins/bmad/skills/bmad-agent-builder/templates/init-template.md b/plugins/bmad/skills/bmad-agent-builder/assets/init-template.md similarity index 100% rename from plugins/bmad/skills/bmad-agent-builder/templates/init-template.md rename to plugins/bmad/skills/bmad-agent-builder/assets/init-template.md diff --git a/plugins/bmad/skills/bmad-agent-builder/templates/memory-system.md b/plugins/bmad/skills/bmad-agent-builder/assets/memory-system.md similarity index 98% rename from plugins/bmad/skills/bmad-agent-builder/templates/memory-system.md rename to plugins/bmad/skills/bmad-agent-builder/assets/memory-system.md index 1301c5b..8c3946c 100644 --- a/plugins/bmad/skills/bmad-agent-builder/templates/memory-system.md +++ b/plugins/bmad/skills/bmad-agent-builder/assets/memory-system.md @@ -126,4 +126,4 @@ Regularly (every few sessions or when files grow large): ## First Run -If sidecar doesn't exist, load `prompts/init.md` to create the structure. +If sidecar doesn't exist, load `init.md` to create the structure. diff --git a/plugins/bmad/skills/bmad-agent-builder/assets/quality-report-template.md b/plugins/bmad/skills/bmad-agent-builder/assets/quality-report-template.md new file mode 100644 index 0000000..b6811db --- /dev/null +++ b/plugins/bmad/skills/bmad-agent-builder/assets/quality-report-template.md @@ -0,0 +1,282 @@ +# Quality Report: {agent-name} + +**Scanned:** {timestamp} +**Skill Path:** {skill-path} +**Report:** {report-file-path} +**Performed By** QualityReportBot-9001 and {user_name} + +## Executive Summary + +- **Total Issues:** {total-issues} +- **Critical:** {critical} | **High:** {high} | **Medium:** {medium} | **Low:** {low} +- **Overall Quality:** {Excellent|Good|Fair|Poor} +- **Overall Cohesion:** {cohesion-score} +- **Craft Assessment:** {craft-assessment} + + +{executive-narrative} + +### Issues by Category + +| Category | Critical | High | Medium | Low | +|----------|----------|------|--------|-----| +| Structure & Capabilities | {n} | {n} | {n} | {n} | +| Prompt Craft | {n} | {n} | {n} | {n} | +| Execution Efficiency | {n} | {n} | {n} | {n} | +| Path & Script Standards | {n} | {n} | {n} | {n} | +| Agent Cohesion | {n} | {n} | {n} | {n} | +| Creative | — | — | {n} | {n} | + +--- + +## Agent Identity + + + +- **Persona:** {persona-summary} +- **Primary Purpose:** {primary-purpose} +- **Capabilities:** {capability-count} + +--- + +## Strengths + +*What this agent does well — preserve these during optimization:* + + + +{strengths-list} + +--- + +{if-truly-broken} +## Truly Broken or Missing + +*Issues that prevent the agent from working correctly:* + + + +{truly-broken-findings} + +--- +{/if-truly-broken} + +## Detailed Findings by Category + +### 1. Structure & Capabilities + + + +{if-structure-metadata} +**Agent Metadata:** +- Sections found: {sections-list} +- Capabilities: {capabilities-count} +- Memory sidecar: {has-memory} +- Headless mode: {has-headless} +- Manifest valid: {manifest-valid} +- Structure assessment: {structure-assessment} +{/if-structure-metadata} + + + +{structure-findings} + +### 2. Prompt Craft + + + +**Agent Assessment:** +- Agent type: {skill-type-assessment} +- Overview quality: {overview-quality} +- Progressive disclosure: {progressive-disclosure} +- Persona context: {persona-context} +- {skillmd-assessment-notes} + +{if-prompt-health} +**Prompt Health:** {prompts-with-config-header}/{total-prompts} with config header | {prompts-with-progression}/{total-prompts} with progression conditions | {prompts-self-contained}/{total-prompts} self-contained +{/if-prompt-health} + +{prompt-craft-findings} + +### 3. Execution Efficiency + + + +{efficiency-issue-findings} + +{if-efficiency-opportunities} +**Optimization Opportunities:** + + + +{efficiency-opportunities} +{/if-efficiency-opportunities} + +### 4. Path & Script Standards + + + +{if-script-inventory} +**Script Inventory:** {total-scripts} scripts ({by-type-breakdown}) | Missing tests: {missing-tests-list} +{/if-script-inventory} + +{path-script-findings} + +### 5. Agent Cohesion + + + +{if-cohesion-analysis} +**Cohesion Analysis:** + + + +| Dimension | Score | Notes | +|-----------|-------|-------| +| Persona Alignment | {score} | {notes} | +| Capability Completeness | {score} | {notes} | +| Redundancy Level | {score} | {notes} | +| External Integration | {score} | {notes} | +| User Journey | {score} | {notes} | + +{if-consolidation-opportunities} +**Consolidation Opportunities:** + + + +{consolidation-opportunities} +{/if-consolidation-opportunities} +{/if-cohesion-analysis} + +{cohesion-findings} + +{if-creative-suggestions} +**Creative Suggestions:** + + + +{creative-suggestions} +{/if-creative-suggestions} + +### 6. Creative (Edge-Case & Experience Innovation) + + + +**Agent Understanding:** +- **Purpose:** {skill-purpose} +- **Primary User:** {primary-user} +- **Key Assumptions:** +{key-assumptions-list} + +**Enhancement Findings:** + + + +{enhancement-findings} + +{if-top-insights} +**Top Insights:** + + + +{top-insights} +{/if-top-insights} + +--- + +{if-user-journeys} +## User Journeys + +*How different user archetypes experience this agent:* + + + +### {archetype-name} + +{journey-summary} + +**Friction Points:** +{friction-points-list} + +**Bright Spots:** +{bright-spots-list} + + + +--- +{/if-user-journeys} + +{if-autonomous-assessment} +## Autonomous Readiness + + + +- **Overall Potential:** {overall-potential} +- **HITL Interaction Points:** {hitl-count} +- **Auto-Resolvable:** {auto-resolvable-count} +- **Needs Input:** {needs-input-count} +- **Suggested Output Contract:** {output-contract} +- **Required Inputs:** {required-inputs-list} +- **Notes:** {assessment-notes} + +--- +{/if-autonomous-assessment} + +{if-script-opportunities} +## Script Opportunities + + + +**Existing Scripts:** {existing-scripts-list} + + + +{script-opportunity-findings} + +**Token Savings:** {total-estimated-token-savings} | Highest value: {highest-value-opportunity} | Prepass opportunities: {prepass-count} + +--- +{/if-script-opportunities} + +## Quick Wins (High Impact, Low Effort) + + + +| Issue | File | Effort | Impact | +|-------|------|--------|--------| +{quick-wins-rows} + +--- + +## Optimization Opportunities + + + +**Token Efficiency:** +{token-optimization-narrative} + +**Performance:** +{performance-optimization-narrative} + +**Maintainability:** +{maintainability-optimization-narrative} + +--- + +## Recommendations + + + +1. {recommendation-1} +2. {recommendation-2} +3. {recommendation-3} +4. {recommendation-4} +5. {recommendation-5} diff --git a/plugins/bmad/skills/bmad-agent-builder/templates/save-memory.md b/plugins/bmad/skills/bmad-agent-builder/assets/save-memory.md similarity index 100% rename from plugins/bmad/skills/bmad-agent-builder/templates/save-memory.md rename to plugins/bmad/skills/bmad-agent-builder/assets/save-memory.md diff --git a/plugins/bmad/skills/bmad-agent-builder/bmad-manifest.json b/plugins/bmad/skills/bmad-agent-builder/bmad-manifest.json index eaa12bd..d9a6ace 100644 --- a/plugins/bmad/skills/bmad-agent-builder/bmad-manifest.json +++ b/plugins/bmad/skills/bmad-agent-builder/bmad-manifest.json @@ -7,7 +7,7 @@ "menu-code": "BP", "description": "Build, edit, or convert agents through six-phase conversational discovery. Covers new agents, format conversion, edits, and fixes.", "supports-headless": true, - "prompt": "prompts/build-process.md", + "prompt": "build-process.md", "phase-name": "anytime", "output-location": "{bmad_builder_output_folder}" }, @@ -16,7 +16,7 @@ "menu-code": "QO", "description": "Comprehensive validation and optimization using lint scripts and LLM scanner subagents. Structure, prompt craft, efficiency, and more.", "supports-headless": true, - "prompt": "prompts/quality-optimizer.md", + "prompt": "quality-optimizer.md", "phase-name": "anytime", "output-location": "{bmad_builder_reports}" } diff --git a/plugins/bmad/skills/bmad-agent-builder/prompts/build-process.md b/plugins/bmad/skills/bmad-agent-builder/build-process.md similarity index 77% rename from plugins/bmad/skills/bmad-agent-builder/prompts/build-process.md rename to plugins/bmad/skills/bmad-agent-builder/build-process.md index 07ad158..4eb52cf 100644 --- a/plugins/bmad/skills/bmad-agent-builder/prompts/build-process.md +++ b/plugins/bmad/skills/bmad-agent-builder/build-process.md @@ -65,7 +65,7 @@ Work through these conversationally: - **Checkpoint data** (save periodically): What can be batched and saved occasionally? - **Save triggers:** After which interactions should memory be updated? - **Capabilities:** - - **Internal prompts:** Capabilities the agent knows itself (each will get a prompt file in `prompts/`) + - **Internal prompts:** Capabilities the agent knows itself (each will get its own prompt file) - **External skills:** Skills the agent invokes (ask for **exact registered skill names** — e.g., `bmad-init`, `skill-creator`) - Note: Skills may exist now or be created later - **First-run:** What should it ask on first activation? (standalone only; module-based gets config from module's config.yaml) @@ -87,7 +87,7 @@ Work through these conversationally: - **Path Conventions** (CRITICAL for reliable agent behavior): - **Memory location:** `{project-root}/_bmad/_memory/{skillName}-sidecar/` - **Project artifacts:** `{project-root}/_bmad/...` when referencing project-level files - - **Skill-internal files:** Use relative paths (`resources/`, `prompts/`, `scripts/`) + - **Skill-internal files:** Use relative paths (`references/`, `scripts/`) - **Config variables:** Use directly — they already contain full paths (NO `{project-root}` prefix) - Correct: `{output_folder}/file.md` - Wrong: `{project-root}/{output_folder}/file.md` (double-prefix breaks resolution) @@ -100,19 +100,19 @@ Once you have a cohesive idea, think one level deeper. Once you have done this, ## Phase 5: Build **Always load these before building:** -- Load `resources/standard-fields.md` — field definitions, description format, path rules -- Load `resources/skill-best-practices.md` — authoring patterns (freedom levels, templates, anti-patterns) -- Load `resources/quality-dimensions.md` — quick mental checklist for build quality +- Load `references/standard-fields.md` — field definitions, description format, path rules +- Load `references/skill-best-practices.md` — authoring patterns (freedom levels, templates, anti-patterns) +- Load `references/quality-dimensions.md` — quick mental checklist for build quality **Load based on context:** -- **If module-based:** Load `resources/metadata-reference.md` — manifest.json field definitions, module metadata structure, config loading requirements -- **Always load** `resources/script-opportunities-reference.md` — script opportunity spotting guide, catalog, and output standards. Use this to identify additional script opportunities not caught in Phase 2, even if no scripts were initially planned. +- **If module-based:** Load `references/metadata-reference.md` — manifest.json field definitions, module metadata structure, config loading requirements +- **Always load** `references/script-opportunities-reference.md` — script opportunity spotting guide, catalog, and output standards. Use this to identify additional script opportunities not caught in Phase 2, even if no scripts were initially planned. When confirmed: -1. Load template substitution rules from `resources/template-substitution-rules.md` and apply +1. Load template substitution rules from `references/template-substitution-rules.md` and apply -2. Create skill structure using templates from `templates/` folder: +2. Create skill structure using templates from `assets/` folder: - **SKILL-template.md** — skill wrapper with full persona content embedded - **init-template.md** — first-run setup (if sidecar) - **memory-system.md** — memory (if sidecar, saved at root level) @@ -132,7 +132,7 @@ When confirmed: python3 scripts/manifest.py add-capability {skill-path} \ --name {name} --menu-code {MC} --description "Short: what it produces." \ --supports-autonomous \ - --prompt prompts/{name}.md # internal capability + --prompt {name}.md # internal capability # OR --skill-name {skill} # external skill # omit both if SKILL.md handles it directly @@ -150,22 +150,32 @@ When confirmed: --is-required ``` -4. **Folder structure** (no `assets/` folder — everything at root): +4. **Folder structure:** ``` {skill-name}/ -├── SKILL.md # Contains full persona content (agent.md embedded) -├── bmad-manifest.json # Capabilities, persona, memory, module integration -├── resources/ -│ └── memory-system.md # (if sidecar needed) -├── scripts/ # python or shell scripts needed for the agent -│ └── run-tests.sh # uvx-powered test runner (if python tests exist) -└── prompts/ # Internal capability prompts - ├── init.md # First-run setup - ├── autonomous-wake.md # Autonomous activation (if autonomous mode) - ├── save-memory.md # Explicit memory save (if sidecar) - └── {name}.md # Each internal capability prompt +├── SKILL.md # Contains full persona content (agent.md embedded) +├── bmad-manifest.json # Capabilities, persona, memory, module integration +├── init.md # First-run setup (if sidecar) +├── autonomous-wake.md # Autonomous activation (if autonomous mode) +├── save-memory.md # Explicit memory save (if sidecar) +├── {name}.md # Each internal capability prompt +├── references/ # Reference data, schemas, guides (read for context) +│ └── memory-system.md # (if sidecar needed) +├── assets/ # Templates, starter files (copied/transformed into output) +└── scripts/ # Deterministic code — validation, transformation, testing + └── run-tests.sh # uvx-powered test runner (if python tests exist) ``` +**What goes where:** +| Location | Contains | LLM relationship | +|----------|----------|-----------------| +| **Root `.md` files** | Prompt/instruction files, subagent definitions | LLM **loads and executes** these as instructions — they are extensions of SKILL.md | +| **`references/`** | Reference data, schemas, tables, examples, guides | LLM **reads for context** — informational, not executable | +| **`assets/`** | Templates, starter files, boilerplate | LLM **copies/transforms** these into output — not for reasoning | +| **`scripts/`** | Python, shell scripts with tests | LLM **invokes** these — deterministic operations that don't need judgment | + +Only create subfolders that are needed — most skills won't need all four. + 5. Output to `bmad_builder_output_folder` from config, or `{project-root}/bmad-builder-creations/` 6. **Lint gate** — run deterministic validation scripts: @@ -184,6 +194,6 @@ Present what was built: location, structure, first-run behavior, capabilities. A Ask: *"Build is done. Would you like to run a Quality Scan to optimize the agent further?"* -If yes, load `prompts/quality-optimizer.md` with `{scan_mode}=full` and the agent path. +If yes, load `quality-optimizer.md` with `{scan_mode}=full` and the agent path. Remind them: BMad module system compliant. Use `bmad-init` skill to integrate into a project. diff --git a/plugins/bmad/skills/bmad-agent-builder/prompts/quality-optimizer.md b/plugins/bmad/skills/bmad-agent-builder/quality-optimizer.md similarity index 79% rename from plugins/bmad/skills/bmad-agent-builder/prompts/quality-optimizer.md rename to plugins/bmad/skills/bmad-agent-builder/quality-optimizer.md index 28a7cfe..2e22591 100644 --- a/plugins/bmad/skills/bmad-agent-builder/prompts/quality-optimizer.md +++ b/plugins/bmad/skills/bmad-agent-builder/quality-optimizer.md @@ -75,7 +75,7 @@ These run instantly, cost zero tokens, and produce structured JSON: | # | Script | Focus | Temp Filename | |---|--------|-------|---------------| -| S1 | `scripts/scan-path-standards.py` | Path conventions: no {skill-root}, {project-root} only for _bmad, bare _bmad, memory paths, double-prefix | `path-standards-temp.json` | +| S1 | `scripts/scan-path-standards.py` | Path conventions: {project-root} only for _bmad, bare _bmad, memory paths, double-prefix, absolute paths | `path-standards-temp.json` | | S2 | `scripts/scan-scripts.py` | Script portability, PEP 723, agentic design, unit tests | `scripts-temp.json` | ### Pre-Pass Scripts (Feed LLM Scanners) @@ -92,12 +92,12 @@ These extract metrics for the LLM scanners so they work from compact data instea | # | Scanner | Focus | Pre-Pass? | Temp Filename | |---|---------|-------|-----------|---------------| -| L1 | `agents/quality-scan-structure.md` | Structure, capabilities, identity, memory setup, consistency | Yes — receives prepass JSON | `structure-temp.json` | -| L2 | `agents/quality-scan-prompt-craft.md` | Token efficiency, anti-patterns, outcome balance, persona voice, Overview quality | Yes — receives metrics JSON | `prompt-craft-temp.json` | -| L3 | `agents/quality-scan-execution-efficiency.md` | Parallelization, subagent delegation, memory loading, context optimization | Yes — receives dep graph JSON | `execution-efficiency-temp.json` | -| L4 | `agents/quality-scan-agent-cohesion.md` | Persona-capability alignment, gaps, redundancies, coherence | No | `agent-cohesion-temp.json` | -| L5 | `agents/quality-scan-enhancement-opportunities.md` | Script automation, autonomous potential, edge cases, experience gaps, delight | No | `enhancement-opportunities-temp.json` | -| L6 | `agents/quality-scan-script-opportunities.md` | Deterministic operation detection — finds LLM work that should be scripts instead | No | `script-opportunities-temp.json` | +| L1 | `quality-scan-structure.md` | Structure, capabilities, identity, memory setup, consistency | Yes — receives prepass JSON | `structure-temp.json` | +| L2 | `quality-scan-prompt-craft.md` | Token efficiency, anti-patterns, outcome balance, persona voice, Overview quality | Yes — receives metrics JSON | `prompt-craft-temp.json` | +| L3 | `quality-scan-execution-efficiency.md` | Parallelization, subagent delegation, memory loading, context optimization | Yes — receives dep graph JSON | `execution-efficiency-temp.json` | +| L4 | `quality-scan-agent-cohesion.md` | Persona-capability alignment, gaps, redundancies, coherence | No | `agent-cohesion-temp.json` | +| L5 | `quality-scan-enhancement-opportunities.md` | Script automation, autonomous potential, edge cases, experience gaps, delight | No | `enhancement-opportunities-temp.json` | +| L6 | `quality-scan-script-opportunities.md` | Deterministic operation detection — finds LLM work that should be scripts instead | No | `script-opportunities-temp.json` | ## Execution Instructions @@ -125,7 +125,7 @@ After scripts complete, spawn applicable LLM scanners as parallel subagents. **For scanners WITHOUT pre-pass (L4, L5, L6):** provide just the skill path and output directory. Each subagent receives: -- Scanner file to load (e.g., `agents/quality-scan-agent-cohesion.md`) +- Scanner file to load (e.g., `quality-scan-agent-cohesion.md`) - Skill path to scan: `{skill-path}` - Output directory for results: `{quality-report-dir}` - Temp filename for output: `{temp-filename}` @@ -151,13 +151,23 @@ After all scripts and scanners complete: 3. Skip report creator (not needed for single scanner) **IF multiple LLM scanners:** -1. Initiate a subagent with `agents/report-quality-scan-creator.md` +1. Initiate a subagent with `report-quality-scan-creator.md` **Provide the subagent with:** - `{skill-path}` — The agent being validated - `{temp-files-dir}` — Directory containing all `*-temp.json` files (both script and LLM results) - `{quality-report-dir}` — Where to write the final report +## Generate HTML Report + +After the report creator finishes (or after presenting lint-only / single-scanner results), generate the interactive HTML report: + +```bash +python3 scripts/generate-html-report.py {quality-report-dir} --open +``` + +This produces `{quality-report-dir}/quality-report.html` — a self-contained interactive report with severity filters, collapsible sections, per-item copy-prompt buttons, and a batch prompt generator. The `--open` flag opens it in the default browser. + ## Present Findings to User After receiving the JSON summary from the report creator: @@ -169,6 +179,7 @@ After receiving the JSON summary from the report creator: "headless_mode": true, "scan_completed": true, "report_file": "{full-path-to-report}", + "html_report": "{full-path-to-html}", "warnings": ["any warnings from pre-scan checks"], "summary": { "total_issues": 0, @@ -186,10 +197,10 @@ After receiving the JSON summary from the report creator: **IF `{headless_mode}=false` or not set:** 1. **High-level summary** with total issues by severity 2. **Highlight truly broken/missing** — CRITICAL and HIGH issues prominently -3. **Mention detailed report** — "Full report saved to: {report_file}" +3. **Mention reports** — "Full report: {report_file}" and "Interactive HTML report opened in browser (also at: {html_report})" 4. **Offer next steps:** - Apply fixes directly - - Export checklist for manual fixes + - Use the HTML report to select specific items and generate prompts - Discuss specific findings ## Key Principle diff --git a/plugins/bmad/skills/bmad-agent-builder/agents/quality-scan-agent-cohesion.md b/plugins/bmad/skills/bmad-agent-builder/quality-scan-agent-cohesion.md similarity index 77% rename from plugins/bmad/skills/bmad-agent-builder/agents/quality-scan-agent-cohesion.md rename to plugins/bmad/skills/bmad-agent-builder/quality-scan-agent-cohesion.md index 440ef71..66a8f17 100644 --- a/plugins/bmad/skills/bmad-agent-builder/agents/quality-scan-agent-cohesion.md +++ b/plugins/bmad/skills/bmad-agent-builder/quality-scan-agent-cohesion.md @@ -22,8 +22,8 @@ This is an **opinionated, advisory scan**. Findings are suggestions, not errors. Find and read: - `SKILL.md` — Identity, persona, principles, description - `bmad-manifest.json` — All capabilities with menu codes and descriptions -- `prompts/*.md` — What each prompt actually does -- `resources/dimension-definitions.md` — If exists, context for capability design +- `*.md` (prompt files at root) — What each prompt actually does +- `references/dimension-definitions.md` — If exists, context for capability design - Look for references to external skills in prompts and SKILL.md ## Cohesion Dimensions @@ -143,6 +143,12 @@ Find and read: ## Output Format +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. + +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? + You will receive `{skill-path}` and `{quality-report-dir}` as inputs. Write JSON findings to: `{quality-report-dir}/agent-cohesion-temp.json` @@ -151,69 +157,57 @@ Write JSON findings to: `{quality-report-dir}/agent-cohesion-temp.json` { "scanner": "agent-cohesion", "agent_path": "{path}", - "agent_identity": { - "name": "{skill-name}", - "persona_summary": "Brief characterization of who this agent is", - "primary_purpose": "What this agent is for", - "capability_count": 12 - }, "findings": [ { - "file": "SKILL.md|bmad-manifest.json|prompts/{name}.md", - "severity": "high|medium|low|suggestion", + "file": "SKILL.md|bmad-manifest.json|{name}.md", + "severity": "high|medium|low|suggestion|strength", "category": "gap|redundancy|misalignment|opportunity|strength", - "issue": "Brief description", - "observation": "What you noticed that led to this finding", - "rationale": "Why this matters for cohesion", - "suggestion": "Specific improvement idea", - "impact": "What value this would add if addressed" + "title": "Brief description", + "detail": "What you noticed, why this matters for cohesion, and what value addressing it would add", + "action": "Specific improvement idea" } ], - "cohesion_analysis": { - "persona_alignment": { - "score": "strong|moderate|weak", - "notes": "Brief explanation of why persona fits or doesn't fit capabilities" - }, - "capability_completeness": { - "score": "complete|mostly-complete|gaps-obvious", - "missing_areas": ["area1", "area2"], - "notes": "What's missing that should probably be there" - }, - "redundancy_level": { - "score": "clean|some-overlap|significant-redundancy", - "consolidation_opportunities": [ - { - "capabilities": ["cap-a", "cap-b", "cap-c"], - "suggested_consolidation": "How these could be combined" - } - ] + "assessments": { + "agent_identity": { + "name": "{skill-name}", + "persona_summary": "Brief characterization of who this agent is", + "primary_purpose": "What this agent is for", + "capability_count": 12 }, - "external_integration": { - "external_skills_referenced": 3, - "integration_pattern": "intentional|incidental|unclear", - "notes": "How external skills fit into the overall design" - }, - "user_journey_score": { - "score": "complete-end-to-end|mostly-complete|fragmented", - "broken_workflows": ["workflow that can't be completed"], - "notes": "Can a user accomplish real work with this agent?" + "cohesion_analysis": { + "persona_alignment": { + "score": "strong|moderate|weak", + "notes": "Brief explanation of why persona fits or doesn't fit capabilities" + }, + "capability_completeness": { + "score": "complete|mostly-complete|gaps-obvious", + "missing_areas": ["area1", "area2"], + "notes": "What's missing that should probably be there" + }, + "redundancy_level": { + "score": "clean|some-overlap|significant-redundancy", + "consolidation_opportunities": [ + { + "capabilities": ["cap-a", "cap-b", "cap-c"], + "suggested_consolidation": "How these could be combined" + } + ] + }, + "external_integration": { + "external_skills_referenced": 3, + "integration_pattern": "intentional|incidental|unclear", + "notes": "How external skills fit into the overall design" + }, + "user_journey_score": { + "score": "complete-end-to-end|mostly-complete|fragmented", + "broken_workflows": ["workflow that can't be completed"], + "notes": "Can a user accomplish real work with this agent?" + } } }, - "creative_suggestions": [ - { - "type": "new-capability|consolidation|refinement|persona-shift", - "idea": "Brief creative suggestion for improvement", - "rationale": "Why this would strengthen the agent", - "estimated_impact": "high|medium|low" - } - ], - "strengths": [ - "Something this agent does really well - positive feedback is useful!", - "Another strength..." - ], "summary": { "total_findings": 0, - "by_severity": {"high": 0, "medium": 0, "low": 0, "suggestion": 0}, + "by_severity": {"high": 0, "medium": 0, "low": 0, "suggestion": 0, "strength": 0}, "by_category": {"gap": 0, "redundancy": 0, "misalignment": 0, "opportunity": 0, "strength": 0}, "overall_cohesion": "cohesive|mostly-cohesive|fragmented|confused", "single_most_important_fix": "The ONE thing that would most improve this agent" @@ -221,6 +215,11 @@ Write JSON findings to: `{quality-report-dir}/agent-cohesion-temp.json` } ``` +Merge all findings into the single `findings[]` array: +- Former `findings[]` items: map `issue` to `title`, merge `observation`+`rationale`+`impact` into `detail`, map `suggestion` to `action` +- Former `strengths[]` items: use `severity: "strength"`, `category: "strength"` +- Former `creative_suggestions[]` items: use `severity: "suggestion"`, map `idea` to `title`, `rationale` to `detail`, merge `type` and `estimated_impact` context into `detail`, map actionable recommendation to `action` + ## Severity Guidelines | Severity | When to Use | diff --git a/plugins/bmad/skills/bmad-agent-builder/agents/quality-scan-enhancement-opportunities.md b/plugins/bmad/skills/bmad-agent-builder/quality-scan-enhancement-opportunities.md similarity index 87% rename from plugins/bmad/skills/bmad-agent-builder/agents/quality-scan-enhancement-opportunities.md rename to plugins/bmad/skills/bmad-agent-builder/quality-scan-enhancement-opportunities.md index a9e179b..df2b565 100644 --- a/plugins/bmad/skills/bmad-agent-builder/agents/quality-scan-enhancement-opportunities.md +++ b/plugins/bmad/skills/bmad-agent-builder/quality-scan-enhancement-opportunities.md @@ -27,9 +27,9 @@ You are NOT checking structure, craft quality, performance, or test coverage — Find and read: - `SKILL.md` — Understand the agent's purpose, persona, audience, and flow -- `prompts/*.md` — Walk through each capability as a user would experience it -- `resources/*.md` — Understand what supporting material exists -- `resources/*.json` — See what supporting schemas exist +- `*.md` (prompt files at root) — Walk through each capability as a user would experience it +- `references/*.md` — Understand what supporting material exists +- `references/*.json` — See what supporting schemas exist ## Creative Analysis Lenses @@ -165,6 +165,12 @@ For each journey, note: ## Output Format +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. + +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? + You will receive `{skill-path}` and `{quality-report-dir}` as inputs. Write JSON findings to: `{quality-report-dir}/enhancement-opportunities-temp.json` @@ -173,46 +179,47 @@ Write JSON findings to: `{quality-report-dir}/enhancement-opportunities-temp.jso { "scanner": "enhancement-opportunities", "skill_path": "{path}", - "skill_understanding": { - "purpose": "What this agent is trying to do", - "primary_user": "Who this agent is for", - "key_assumptions": ["assumption 1", "assumption 2"] - }, "findings": [ { - "file": "SKILL.md|prompts/{name}.md", + "file": "SKILL.md|{name}.md", "severity": "high-opportunity|medium-opportunity|low-opportunity", "category": "edge-case|experience-gap|delight-opportunity|assumption-risk|journey-friction|autonomous-potential|facilitative-pattern", - "scenario": "The specific situation or user story that reveals this opportunity", - "insight": "What you noticed and why it matters", - "suggestion": "Concrete, actionable improvement — the tempered version of the wild idea", - "user_impact": "How this would change the user's experience" - } - ], - "user_journeys": [ - { - "archetype": "first-timer|expert|confused|edge-case|hostile-environment|automator", - "journey_summary": "Brief narrative of this user's experience with the agent", - "friction_points": ["moment 1", "moment 2"], - "bright_spots": ["what works well for this user"] + "title": "The specific situation or user story that reveals this opportunity", + "detail": "What you noticed, why it matters, and how this would change the user's experience", + "action": "Concrete, actionable improvement — the tempered version of the wild idea" } ], - "autonomous_assessment": { - "overall_potential": "headless-ready|easily-adaptable|partially-adaptable|fundamentally-interactive", - "hitl_interaction_points": 0, - "auto_resolvable": 0, - "needs_input": 0, - "suggested_output_contract": "What a headless invocation would return", - "required_inputs": ["parameters needed upfront for headless mode"], - "notes": "Brief assessment of autonomous viability" + "assessments": { + "skill_understanding": { + "purpose": "What this agent is trying to do", + "primary_user": "Who this agent is for", + "key_assumptions": ["assumption 1", "assumption 2"] + }, + "user_journeys": [ + { + "archetype": "first-timer|expert|confused|edge-case|hostile-environment|automator", + "summary": "Brief narrative of this user's experience with the agent", + "friction_points": ["moment 1", "moment 2"], + "bright_spots": ["what works well for this user"] + } + ], + "autonomous_assessment": { + "potential": "headless-ready|easily-adaptable|partially-adaptable|fundamentally-interactive", + "hitl_points": 0, + "auto_resolvable": 0, + "needs_input": 0, + "suggested_output_contract": "What a headless invocation would return", + "required_inputs": ["parameters needed upfront for headless mode"], + "notes": "Brief assessment of autonomous viability" + }, + "top_insights": [ + { + "title": "The single most impactful creative observation", + "detail": "The user experience impact", + "action": "What to do about it" + } + ] }, - "top_insights": [ - { - "insight": "The single most impactful creative observation", - "suggestion": "What to do about it", - "why_it_matters": "The user experience impact" - } - ], "summary": { "total_findings": 0, "by_severity": {"high-opportunity": 0, "medium-opportunity": 0, "low-opportunity": 0}, @@ -225,8 +232,7 @@ Write JSON findings to: `{quality-report-dir}/enhancement-opportunities-temp.jso "autonomous_potential": 0, "facilitative_pattern": 0 }, - "boldest_idea": "The wildest suggestion that's still practical — the one that could transform this agent", - "overall_experience_assessment": "Brief creative assessment of the agent's user experience" + "assessment": "Brief creative assessment of the agent's user experience, including the boldest practical idea" } } ``` diff --git a/plugins/bmad/skills/bmad-agent-builder/agents/quality-scan-execution-efficiency.md b/plugins/bmad/skills/bmad-agent-builder/quality-scan-execution-efficiency.md similarity index 83% rename from plugins/bmad/skills/bmad-agent-builder/agents/quality-scan-execution-efficiency.md rename to plugins/bmad/skills/bmad-agent-builder/quality-scan-execution-efficiency.md index ba3e52e..a5b2201 100644 --- a/plugins/bmad/skills/bmad-agent-builder/agents/quality-scan-execution-efficiency.md +++ b/plugins/bmad/skills/bmad-agent-builder/quality-scan-execution-efficiency.md @@ -18,8 +18,8 @@ Pre-pass provides: dependency graph, sequential patterns, loop patterns, subagen Read raw files for judgment calls: - `SKILL.md` — On Activation patterns, operation flow -- `prompts/*.md` — Each prompt for execution patterns -- `resources/*.md` — Resource loading patterns +- `*.md` (prompt files at root) — Each prompt for execution patterns +- `references/*.md` — Resource loading patterns --- @@ -120,6 +120,12 @@ GOOD: Selective loading ## Output Format +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. + +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? + You will receive `{skill-path}` and `{quality-report-dir}` as inputs. Write JSON findings to: `{quality-report-dir}/execution-efficiency-temp.json` @@ -128,34 +134,29 @@ Write JSON findings to: `{quality-report-dir}/execution-efficiency-temp.json` { "scanner": "execution-efficiency", "skill_path": "{path}", - "issues": [ + "findings": [ { - "file": "SKILL.md|prompts/{name}.md", + "file": "SKILL.md|{name}.md", "line": 42, - "severity": "critical|high|medium|low", - "category": "sequential-independent|parent-reads-first|missing-batch|no-output-spec|subagent-chain-violation|memory-loading|resource-loading|missing-delegation", - "issue": "Brief description", - "current_pattern": "What it does now", - "efficient_alternative": "What it should do instead", - "estimated_savings": "Time/token savings estimate" - } - ], - "opportunities": [ - { - "type": "parallelization|batching|delegation|memory-optimization|resource-optimization", - "description": "What could be improved", - "recommendation": "Specific improvement", - "estimated_savings": "Estimated improvement" + "severity": "critical|high|medium|low|medium-opportunity", + "category": "sequential-independent|parent-reads-first|missing-batch|no-output-spec|subagent-chain-violation|memory-loading|resource-loading|missing-delegation|parallelization|batching|delegation|memory-optimization|resource-optimization", + "title": "Brief description", + "detail": "What it does now, and estimated time/token savings", + "action": "What it should do instead" } ], "summary": { - "total_issues": 0, + "total_findings": 0, "by_severity": {"critical": 0, "high": 0, "medium": 0, "low": 0}, "by_category": {} } } ``` +Merge all items into the single `findings[]` array: +- Former `issues[]` items: map `issue` to `title`, merge `current_pattern`+`estimated_savings` into `detail`, map `efficient_alternative` to `action` +- Former `opportunities[]` items: map `description` to `title`, merge details into `detail`, map `recommendation` to `action`, use severity like `medium-opportunity` + ## Process 1. Read pre-pass JSON at `{quality-report-dir}/execution-deps-prepass.json` diff --git a/plugins/bmad/skills/bmad-agent-builder/agents/quality-scan-prompt-craft.md b/plugins/bmad/skills/bmad-agent-builder/quality-scan-prompt-craft.md similarity index 85% rename from plugins/bmad/skills/bmad-agent-builder/agents/quality-scan-prompt-craft.md rename to plugins/bmad/skills/bmad-agent-builder/quality-scan-prompt-craft.md index 1e9aa45..ee41330 100644 --- a/plugins/bmad/skills/bmad-agent-builder/agents/quality-scan-prompt-craft.md +++ b/plugins/bmad/skills/bmad-agent-builder/quality-scan-prompt-craft.md @@ -20,8 +20,8 @@ Pre-pass provides: line counts, token estimates, section inventories, waste patt Read raw files for judgment calls: - `SKILL.md` — Overview quality, persona context assessment -- `prompts/*.md` — Each capability prompt for craft quality -- `resources/*.md` — Progressive disclosure assessment +- `*.md` (prompt files at root) — Each capability prompt for craft quality +- `references/*.md` — Progressive disclosure assessment --- @@ -54,9 +54,9 @@ A good agent Overview includes: | Scenario | Acceptable Size | Notes | |----------|----------------|-------| -| Multi-capability agent with brief capability sections | Up to ~250 lines | Each capability section brief, detail in prompts/ | +| Multi-capability agent with brief capability sections | Up to ~250 lines | Each capability section brief, detail in prompt files | | Single-purpose agent with deep persona | Up to ~500 lines (~5000 tokens) | Acceptable if content is genuinely needed | -| Agent with large reference tables or schemas inline | Flag for extraction | These belong in resources/, not SKILL.md | +| Agent with large reference tables or schemas inline | Flag for extraction | These belong in references/, not SKILL.md | ### Detecting Over-Optimization (Under-Contextualized Agents) @@ -72,7 +72,7 @@ A good agent Overview includes: ## Part 2: Capability Prompt Craft -Capability prompts (`prompts/*.md`) are the working instructions for each capability. These should be more procedural than SKILL.md but maintain persona voice consistency. +Capability prompts (prompt `.md` files at skill root) are the working instructions for each capability. These should be more procedural than SKILL.md but maintain persona voice consistency. ### Config Header | Check | Why It Matters | @@ -165,6 +165,12 @@ Do NOT flag these: ## Output Format +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. + +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? + You will receive `{skill-path}` and `{quality-report-dir}` as inputs. Write JSON findings to: `{quality-report-dir}/prompt-craft-temp.json` @@ -173,36 +179,37 @@ Write JSON findings to: `{quality-report-dir}/prompt-craft-temp.json` { "scanner": "prompt-craft", "skill_path": "{path}", - "skill_type_assessment": "simple-utility|domain-expert|companion-interactive|workflow-facilitator", - "skillmd_assessment": { - "overview_quality": "appropriate|excessive|missing|disconnected", - "progressive_disclosure": "good|needs-extraction|monolithic", - "persona_context": "appropriate|excessive|missing", - "notes": "Brief assessment of SKILL.md craft" - }, - "prompts_scanned": 0, - "issues": [ + "findings": [ { - "file": "SKILL.md|prompts/{name}.md", + "file": "SKILL.md|{name}.md", "line": 42, "severity": "critical|high|medium|low|note", "category": "token-waste|anti-pattern|outcome-balance|progression|self-containment|intelligence-placement|overview-quality|progressive-disclosure|under-contextualized|persona-voice|communication-consistency|inline-data", - "issue": "Brief description", - "rationale": "Why this matters for prompt craft", - "fix": "Specific action to resolve", - "nuance": "Optional — why this might be intentional" + "title": "Brief description", + "detail": "Why this matters for prompt craft. Include any nuance about why this might be intentional.", + "action": "Specific action to resolve" } ], - "prompt_health": { - "prompts_with_config_header": 0, - "prompts_with_progression_conditions": 0, - "prompts_self_contained": 0, - "total_prompts": 0 + "assessments": { + "skill_type_assessment": "simple-utility|domain-expert|companion-interactive|workflow-facilitator", + "skillmd_assessment": { + "overview_quality": "appropriate|excessive|missing|disconnected", + "progressive_disclosure": "good|needs-extraction|monolithic", + "persona_context": "appropriate|excessive|missing", + "notes": "Brief assessment of SKILL.md craft" + }, + "prompts_scanned": 0, + "prompt_health": { + "prompts_with_config_header": 0, + "prompts_with_progression_conditions": 0, + "prompts_self_contained": 0, + "total_prompts": 0 + } }, "summary": { - "total_issues": 0, + "total_findings": 0, "by_severity": {"critical": 0, "high": 0, "medium": 0, "low": 0, "note": 0}, - "craft_assessment": "Brief 1-2 sentence assessment", + "assessment": "Brief 1-2 sentence assessment", "top_improvement": "Highest-impact improvement" } } @@ -212,8 +219,8 @@ Write JSON findings to: `{quality-report-dir}/prompt-craft-temp.json` 1. Read pre-pass JSON at `{quality-report-dir}/prompt-metrics-prepass.json` 2. Read SKILL.md — assess agent type, evaluate Overview quality, persona context -3. Read all prompt files in prompts/ -4. Check resources/ for progressive disclosure +3. Read all prompt files at skill root +4. Check references/ for progressive disclosure 5. Evaluate Overview quality (present? appropriate? excessive? missing?) 6. Check for over-optimization — is this a complex agent stripped to bare skeleton? 7. Check size and progressive disclosure diff --git a/plugins/bmad/skills/bmad-agent-builder/agents/quality-scan-script-opportunities.md b/plugins/bmad/skills/bmad-agent-builder/quality-scan-script-opportunities.md similarity index 89% rename from plugins/bmad/skills/bmad-agent-builder/agents/quality-scan-script-opportunities.md rename to plugins/bmad/skills/bmad-agent-builder/quality-scan-script-opportunities.md index 401c5d8..9e5de21 100644 --- a/plugins/bmad/skills/bmad-agent-builder/agents/quality-scan-script-opportunities.md +++ b/plugins/bmad/skills/bmad-agent-builder/quality-scan-script-opportunities.md @@ -16,8 +16,8 @@ Read every prompt file and SKILL.md. For each instruction that tells the LLM to Find and read: - `SKILL.md` — On Activation patterns, inline operations -- `prompts/*.md` — Each capability prompt for deterministic operations hiding in LLM instructions -- `resources/*.md` — Check if any resource content could be generated by scripts instead +- `*.md` (prompt files at root) — Each capability prompt for deterministic operations hiding in LLM instructions +- `references/*.md` — Check if any resource content could be generated by scripts instead - `scripts/` — Understand what scripts already exist (to avoid suggesting duplicates) --- @@ -188,6 +188,12 @@ For each script opportunity found, also assess: ## Output Format +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. + +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? + You will receive `{skill-path}` and `{quality-report-dir}` as inputs. Write JSON findings to: `{quality-report-dir}/script-opportunities-temp.json` @@ -196,32 +202,25 @@ Write JSON findings to: `{quality-report-dir}/script-opportunities-temp.json` { "scanner": "script-opportunities", "skill_path": "{path}", - "existing_scripts": ["list of scripts that already exist in the agent's scripts/ folder"], "findings": [ { - "file": "SKILL.md|prompts/{name}.md", + "file": "SKILL.md|{name}.md", "line": 42, "severity": "high|medium|low", "category": "validation|extraction|transformation|counting|comparison|structure|graph|preprocessing|postprocessing", - "current_behavior": "What the LLM is currently doing", - "script_alternative": "What a script would do instead", - "determinism_confidence": "certain|high|moderate", - "estimated_token_savings": "tokens saved per invocation", - "implementation_complexity": "trivial|moderate|complex", - "language": "python|bash|either", - "could_be_prepass": false, - "feeds_scanner": "scanner name if applicable", - "reusable_across_skills": false, - "help_pattern_savings": "additional prompt tokens saved by using --help instead of inlining interface" + "title": "What the LLM is currently doing", + "detail": "Determinism confidence: certain|high|moderate. Estimated token savings: N per invocation. Implementation complexity: trivial|moderate|complex. Language: python|bash|either. Could be prepass: yes/no. Feeds scanner: name if applicable. Reusable across skills: yes/no. Help pattern savings: additional prompt tokens saved by using --help instead of inlining interface.", + "action": "What a script would do instead" } ], + "assessments": { + "existing_scripts": ["list of scripts that already exist in the agent's scripts/ folder"] + }, "summary": { "total_findings": 0, "by_severity": {"high": 0, "medium": 0, "low": 0}, "by_category": {}, - "total_estimated_token_savings": "aggregate estimate across all findings", - "highest_value_opportunity": "The single biggest win — describe it", - "prepass_opportunities": "How many findings could become pre-pass scripts for LLM scanners" + "assessment": "Brief assessment including total estimated token savings, the single highest-value opportunity, and how many findings could become pre-pass scripts for LLM scanners" } } ``` diff --git a/plugins/bmad/skills/bmad-agent-builder/agents/quality-scan-structure.md b/plugins/bmad/skills/bmad-agent-builder/quality-scan-structure.md similarity index 92% rename from plugins/bmad/skills/bmad-agent-builder/agents/quality-scan-structure.md rename to plugins/bmad/skills/bmad-agent-builder/quality-scan-structure.md index 24fdc1f..e7bceb2 100644 --- a/plugins/bmad/skills/bmad-agent-builder/agents/quality-scan-structure.md +++ b/plugins/bmad/skills/bmad-agent-builder/quality-scan-structure.md @@ -116,6 +116,12 @@ Include all pre-pass findings in your output, preserved as-is. These are determi ## Output Format +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. + +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? + You will receive `{skill-path}` and `{quality-report-dir}` as inputs. Write JSON findings to: `{quality-report-dir}/structure-temp.json` @@ -124,17 +130,18 @@ Write JSON findings to: `{quality-report-dir}/structure-temp.json` { "scanner": "structure", "skill_path": "{path}", - "issues": [ + "findings": [ { - "file": "SKILL.md|bmad-manifest.json|prompts/{name}.md", + "file": "SKILL.md|bmad-manifest.json|{name}.md", "line": 42, "severity": "critical|high|medium|low", "category": "frontmatter|sections|artifacts|manifest|capabilities|identity|communication-style|principles|consistency|memory-setup|headless-mode|activation-sequence", - "issue": "Brief description", - "fix": "Specific action to resolve" + "title": "Brief description", + "detail": "", + "action": "Specific action to resolve" } ], - "metadata": { + "assessments": { "sections_found": ["Overview", "Identity"], "capabilities_count": 0, "has_memory": false, @@ -142,10 +149,10 @@ Write JSON findings to: `{quality-report-dir}/structure-temp.json` "manifest_valid": true }, "summary": { - "total_issues": 0, + "total_findings": 0, "by_severity": {"critical": 0, "high": 0, "medium": 0, "low": 0}, "by_category": {}, - "structure_assessment": "Brief 1-2 sentence assessment" + "assessment": "Brief 1-2 sentence assessment" } } ``` diff --git a/plugins/bmad/skills/bmad-agent-builder/resources/metadata-reference.md b/plugins/bmad/skills/bmad-agent-builder/references/metadata-reference.md similarity index 91% rename from plugins/bmad/skills/bmad-agent-builder/resources/metadata-reference.md rename to plugins/bmad/skills/bmad-agent-builder/references/metadata-reference.md index 73ba3df..4a0b7e7 100644 --- a/plugins/bmad/skills/bmad-agent-builder/resources/metadata-reference.md +++ b/plugins/bmad/skills/bmad-agent-builder/references/metadata-reference.md @@ -36,7 +36,7 @@ description: [5-8 word summary]. [Use when user says 'X' or 'Y'.] "menu-code": "BP", "description": "Builds agents through conversational discovery. Outputs to skill folder.", "supports-headless": true, - "prompt": "prompts/build-process.md", + "prompt": "build-process.md", "phase-name": "anytime", "after": ["create-prd"], "before": [], @@ -103,7 +103,7 @@ All module skills MUST use the `bmad-init` skill at startup. ## Path Construction Rules — CRITICAL -Never use `{skill-root}`. Only use `{project-root}` for `_bmad` paths. +Only use `{project-root}` for `_bmad` paths. **Three path types:** - **Skill-internal** — bare relative paths (no prefix) @@ -112,15 +112,15 @@ Never use `{skill-root}`. Only use `{project-root}` for `_bmad` paths. **Correct:** ``` -resources/reference.md # Skill-internal (bare relative) -prompts/capability.md # Skill-internal (bare relative) +references/reference.md # Skill-internal (bare relative) +capability.md # Skill-internal (bare relative) {project-root}/_bmad/_memory/x-sidecar/ # Project _bmad path {output_folder}/report.md # Config var (already has full path) ``` **Never use:** ``` -{skill-root}/resources/reference.md # {skill-root} doesn't exist +../../other-skill/file.md # Cross-skill relative path breaks with reorganization {project-root}/{config_var}/output.md # Double-prefix -./resources/reference.md # Relative prefix breaks context changes +./references/reference.md # Relative prefix breaks context changes ``` diff --git a/plugins/bmad/skills/bmad-agent-builder/resources/quality-dimensions.md b/plugins/bmad/skills/bmad-agent-builder/references/quality-dimensions.md similarity index 79% rename from plugins/bmad/skills/bmad-agent-builder/resources/quality-dimensions.md rename to plugins/bmad/skills/bmad-agent-builder/references/quality-dimensions.md index f79b595..064d17c 100644 --- a/plugins/bmad/skills/bmad-agent-builder/resources/quality-dimensions.md +++ b/plugins/bmad/skills/bmad-agent-builder/references/quality-dimensions.md @@ -22,9 +22,10 @@ Scripts handle plumbing (fetch, transform, validate). Prompts handle judgment (i SKILL.md stays focused. Detail goes where it belongs. -- Capability instructions → `prompts/` -- Reference data, schemas, large tables → `resources/` -- Memory discipline → `resources/memory-system.md` +- Capability instructions → prompt files at skill root +- Reference data, schemas, large tables → `references/` +- Templates, starter files → `assets/` +- Memory discipline → `references/memory-system.md` - Multi-capability SKILL.md under ~250 lines: fine as-is - Single-purpose up to ~500 lines: acceptable if focused @@ -32,13 +33,13 @@ SKILL.md stays focused. Detail goes where it belongs. Two parts: `[5-8 word summary]. [Use when user says 'X' or 'Y'.]` -Default to conservative triggering. See `resources/standard-fields.md` for full format and examples. +Default to conservative triggering. See `references/standard-fields.md` for full format and examples. ## 5. Path Construction -Never use `{skill-root}`. Only use `{project-root}` for `_bmad` paths. Config variables used directly — they already contain `{project-root}`. +Only use `{project-root}` for `_bmad` paths. Config variables used directly — they already contain `{project-root}`. -See `resources/standard-fields.md` for correct/incorrect patterns. +See `references/standard-fields.md` for correct/incorrect patterns. ## 6. Token Efficiency diff --git a/plugins/bmad/skills/bmad-agent-builder/resources/script-opportunities-reference.md b/plugins/bmad/skills/bmad-agent-builder/references/script-opportunities-reference.md similarity index 97% rename from plugins/bmad/skills/bmad-agent-builder/resources/script-opportunities-reference.md rename to plugins/bmad/skills/bmad-agent-builder/references/script-opportunities-reference.md index d890f95..fecbed0 100644 --- a/plugins/bmad/skills/bmad-agent-builder/resources/script-opportunities-reference.md +++ b/plugins/bmad/skills/bmad-agent-builder/references/script-opportunities-reference.md @@ -1,6 +1,6 @@ # Quality Scan Script Opportunities — Reference Guide -**Reference: `resources/script-standards.md` for script creation guidelines.** +**Reference: `references/script-standards.md` for script creation guidelines.** This document identifies deterministic operations that should be offloaded from the LLM into scripts for quality validation of BMad agents. @@ -119,7 +119,7 @@ All scripts use PEP 723 and `--help`. When a skill's prompt needs to invoke a sc - ## Read Access section exists - ## Write Access section exists - ## Deny Zones section exists (can be empty) -- Paths use placeholders correctly ({project-root} for _bmad paths, relative for skill-internal, no {skill-root}) +- Paths use placeholders correctly ({project-root} for _bmad paths, relative for skill-internal) ``` **Output:** Structured JSON of read/write/deny zones @@ -136,7 +136,7 @@ All scripts use PEP 723 and `--help`. When a skill's prompt needs to invoke a sc **Checks:** ```python -# For each prompt in prompts/: +# For each prompt .md file at skill root: - Has frontmatter (name, description, menu-code) - name matches manifest capability name - menu-code matches manifest (case-insensitive) @@ -145,7 +145,7 @@ All scripts use PEP 723 and `--help`. When a skill's prompt needs to invoke a sc **Output:** JSON with mismatches, missing files -**Implementation:** Python, reads bmad-manifest.json and all .md files in prompts/ +**Implementation:** Python, reads bmad-manifest.json and all prompt .md files at skill root --- diff --git a/plugins/bmad/skills/bmad-agent-builder/resources/skill-best-practices.md b/plugins/bmad/skills/bmad-agent-builder/references/skill-best-practices.md similarity index 98% rename from plugins/bmad/skills/bmad-agent-builder/resources/skill-best-practices.md rename to plugins/bmad/skills/bmad-agent-builder/references/skill-best-practices.md index 432a502..67cdeb3 100644 --- a/plugins/bmad/skills/bmad-agent-builder/resources/skill-best-practices.md +++ b/plugins/bmad/skills/bmad-agent-builder/references/skill-best-practices.md @@ -1,6 +1,6 @@ # Skill Authoring Best Practices -Practical patterns for writing effective BMad agent skills. For field definitions and description format, see `resources/standard-fields.md`. For quality dimensions, see `resources/quality-dimensions.md`. +Practical patterns for writing effective BMad agent skills. For field definitions and description format, see `references/standard-fields.md`. For quality dimensions, see `references/quality-dimensions.md`. ## Core Principle: Informed Autonomy diff --git a/plugins/bmad/skills/bmad-agent-builder/resources/standard-fields.md b/plugins/bmad/skills/bmad-agent-builder/references/standard-fields.md similarity index 100% rename from plugins/bmad/skills/bmad-agent-builder/resources/standard-fields.md rename to plugins/bmad/skills/bmad-agent-builder/references/standard-fields.md diff --git a/plugins/bmad/skills/bmad-agent-builder/resources/template-substitution-rules.md b/plugins/bmad/skills/bmad-agent-builder/references/template-substitution-rules.md similarity index 94% rename from plugins/bmad/skills/bmad-agent-builder/resources/template-substitution-rules.md rename to plugins/bmad/skills/bmad-agent-builder/references/template-substitution-rules.md index b0e4a87..b3bce15 100644 --- a/plugins/bmad/skills/bmad-agent-builder/resources/template-substitution-rules.md +++ b/plugins/bmad/skills/bmad-agent-builder/references/template-substitution-rules.md @@ -43,9 +43,9 @@ Add user's additional questions to the init.md template, replacing `{custom-init ## Path References All generated agents use these paths: -- `prompts/init.md` — First-run setup -- `prompts/{name}.md` — Individual capability prompts -- `resources/memory-system.md` — Memory discipline (if sidecar needed) +- `init.md` — First-run setup +- `{name}.md` — Individual capability prompts +- `references/memory-system.md` — Memory discipline (if sidecar needed) - `bmad-manifest.json` — Capabilities and metadata with menu codes - `scripts/` — Python/shell scripts for deterministic operations (if needed) diff --git a/plugins/bmad/skills/bmad-agent-builder/references/universal-scan-schema.md b/plugins/bmad/skills/bmad-agent-builder/references/universal-scan-schema.md new file mode 100644 index 0000000..11e6df8 --- /dev/null +++ b/plugins/bmad/skills/bmad-agent-builder/references/universal-scan-schema.md @@ -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 required 'version' field in frontmatter", + "detail": "The SKILL.md frontmatter is missing the version field. This prevents the manifest generator from producing correct output and breaks version-aware consumers.", + "action": "Add 'version: 1.0.0' 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`)? diff --git a/plugins/bmad/skills/bmad-agent-builder/report-quality-scan-creator.md b/plugins/bmad/skills/bmad-agent-builder/report-quality-scan-creator.md new file mode 100644 index 0000000..3a0376e --- /dev/null +++ b/plugins/bmad/skills/bmad-agent-builder/report-quality-scan-creator.md @@ -0,0 +1,138 @@ +# Quality Scan Report Creator + +You are a master quality engineer tech writer agent QualityReportBot-9001. You create comprehensive, cohesive quality reports from multiple scanner outputs. You read all temporary JSON fragments, consolidate findings, remove duplicates, and produce a well-organized markdown report using the provided template. You are quality obsessed — nothing gets dropped. You will never attempt to fix anything — you are a writer, not a fixer. + +## Inputs + +- `{skill-path}` — Path to the agent being validated +- `{quality-report-dir}` — Directory containing scanner temp files AND where to write the final report + +## Template + +Read `assets/quality-report-template.md` for the report structure. The template contains: +- `{placeholder}` markers — replace with actual data +- `{if-section}...{/if-section}` blocks — include only when data exists, omit entirely when empty +- `` — inline guidance for what data to pull and from where; strip from final output + +## Process + +### Step 1: Ingest Everything + +1. Read `assets/quality-report-template.md` +2. List ALL files in `{quality-report-dir}` — both `*-temp.json` (scanner findings) and `*-prepass.json` (structural metrics) +3. Read EVERY JSON file + +### Step 2: Extract All Data Types + +All scanners now use the universal schema defined in `references/universal-scan-schema.md`. Scanner-specific data lives in `assessments{}`, not as top-level keys. + +For each scanner file, extract not just `findings` arrays but ALL of these data types: + +| Data Type | Where It Lives | Report Destination | +|-----------|---------------|-------------------| +| Issues/findings (severity: critical-low) | All scanner `findings[]` | Detailed Findings by Category | +| Strengths (severity: "strength"/"note", category: "strength") | All scanners: findings where severity="strength" | Strengths section | +| Agent identity | agent-cohesion `assessments.agent_identity` | Agent Identity section + Executive Summary | +| Cohesion dimensional analysis | agent-cohesion `assessments.cohesion_analysis` | Cohesion Analysis table | +| Consolidation opportunities | agent-cohesion `assessments.cohesion_analysis.redundancy_level.consolidation_opportunities` | Consolidation Opportunities in Cohesion | +| Creative suggestions | `findings[]` with severity="suggestion" (no separate creative_suggestions array) | Creative Suggestions in Cohesion section | +| Craft & agent assessment | prompt-craft `assessments.skillmd_assessment` (incl. `persona_context`), `assessments.prompt_health`, `summary.assessment` | Prompt Craft section header + Executive Summary | +| Structure metadata | structure `assessments.metadata` (has_memory, has_headless, manifest_valid, etc.) | Structure & Capabilities section header | +| User journeys | enhancement-opportunities `assessments.user_journeys[]` | User Journeys section | +| Autonomous assessment | enhancement-opportunities `assessments.autonomous_assessment` | Autonomous Readiness section | +| Skill understanding | enhancement-opportunities `assessments.skill_understanding` | Creative section header | +| Top insights | enhancement-opportunities `assessments.top_insights[]` | Top Insights in Creative section | +| Optimization opportunities | `findings[]` with severity ending in "-opportunity" (no separate opportunities array) | Optimization Opportunities in Efficiency section | +| Script inventory & token savings | scripts `assessments.script_summary`, script-opportunities `summary` | Scripts sections | +| Prepass metrics | `*-prepass.json` files | Context data points where useful | + +### Step 3: Populate Template + +Fill the template section by section, following the `` guidance in each. Key rules: + +- **Conditional sections:** Only include `{if-...}` blocks when the data exists. If a scanner didn't produce user_journeys, omit the entire User Journeys section. +- **Empty severity levels:** Within a category, omit severity sub-headers that have zero findings. +- **Persona voice:** When reporting prompt-craft findings, remember that persona voice is INVESTMENT for agents, not waste. Reflect the scanner's nuance field if present. +- **Strip comments:** Remove all `` blocks from final output. + +### Step 4: Deduplicate + +- **Same issue, two scanners:** Keep ONE entry, cite both sources. Use the more detailed description. +- **Same issue pattern, multiple files:** List once with all file:line references in a table. +- **Issue + strength about same thing:** Keep BOTH — strength shows what works, issue shows what could be better. +- **Overlapping creative suggestions:** Merge into the richer description. +- **Routing:** "note"/"strength" severity → Strengths section. "suggestion" severity → Creative subsection. Do not mix these into issue lists. + +### Step 5: Verification Pass + +**This step is mandatory.** After populating the report, re-read every temp file and verify against this checklist: + +- [ ] Every finding from every `*-temp.json` findings[] array +- [ ] Agent identity block (persona_summary, primary_purpose, capability_count) +- [ ] All findings with severity="strength" from any scanner +- [ ] All positive notes from prompt-craft (severity="note") +- [ ] Cohesion analysis dimensional scores table (if present) +- [ ] Consolidation opportunities from cohesion redundancy analysis +- [ ] Craft assessment, skill type assessment, and persona context assessment +- [ ] Structure metadata (sections_found, has_memory, has_headless, manifest_valid) +- [ ] ALL user journeys with ALL friction_points and bright_spots per archetype +- [ ] The autonomous_assessment block (all fields) +- [ ] All findings with severity="suggestion" from cohesion scanners +- [ ] All findings with severity ending in "-opportunity" from execution-efficiency +- [ ] assessments.top_insights from enhancement-opportunities +- [ ] Script inventory and token savings from script-opportunities +- [ ] Skill understanding (purpose, primary_user, key_assumptions) +- [ ] Prompt health summary from prompt-craft (if prompts exist) + +If any item was dropped, add it to the appropriate section before writing. + +### Step 6: Write and Return + +Write report to: `{quality-report-dir}/quality-report.md` + +Return JSON: + +```json +{ + "report_file": "{full-path-to-report}", + "summary": { + "total_issues": 0, + "critical": 0, + "high": 0, + "medium": 0, + "low": 0, + "strengths_count": 0, + "enhancements_count": 0, + "user_journeys_count": 0, + "overall_quality": "Excellent|Good|Fair|Poor", + "overall_cohesion": "cohesive|mostly-cohesive|fragmented|confused", + "craft_assessment": "brief summary from prompt-craft", + "truly_broken_found": true, + "truly_broken_count": 0 + }, + "by_category": { + "structure_capabilities": {"critical": 0, "high": 0, "medium": 0, "low": 0}, + "prompt_craft": {"critical": 0, "high": 0, "medium": 0, "low": 0}, + "execution_efficiency": {"critical": 0, "high": 0, "medium": 0, "low": 0}, + "path_script_standards": {"critical": 0, "high": 0, "medium": 0, "low": 0}, + "agent_cohesion": {"critical": 0, "high": 0, "medium": 0, "low": 0}, + "creative": {"high_opportunity": 0, "medium_opportunity": 0, "low_opportunity": 0} + }, + "high_impact_quick_wins": [ + {"issue": "description", "file": "location", "effort": "low"} + ] +} +``` + +## Scanner Reference + +| Scanner | Temp File | Primary Category | +|---------|-----------|-----------------| +| structure | structure-temp.json | Structure & Capabilities | +| prompt-craft | prompt-craft-temp.json | Prompt Craft | +| execution-efficiency | execution-efficiency-temp.json | Execution Efficiency | +| path-standards | path-standards-temp.json | Path & Script Standards | +| scripts | scripts-temp.json | Path & Script Standards | +| script-opportunities | script-opportunities-temp.json | Script Opportunities | +| agent-cohesion | agent-cohesion-temp.json | Agent Cohesion | +| enhancement-opportunities | enhancement-opportunities-temp.json | Creative | diff --git a/plugins/bmad/skills/bmad-agent-builder/scripts/bmad-manifest-schema.json b/plugins/bmad/skills/bmad-agent-builder/scripts/bmad-manifest-schema.json index 90e66db..ea674b5 100644 --- a/plugins/bmad/skills/bmad-agent-builder/scripts/bmad-manifest-schema.json +++ b/plugins/bmad/skills/bmad-agent-builder/scripts/bmad-manifest-schema.json @@ -61,7 +61,7 @@ }, "prompt": { - "description": "Relative path to the prompt file for internal capabilities (e.g., prompts/build-process.md). Omit if handled by SKILL.md directly or if this is an external skill call.", + "description": "Relative path to the prompt file for internal capabilities (e.g., build-process.md). Omit if handled by SKILL.md directly or if this is an external skill call.", "type": "string" }, "skill-name": { diff --git a/plugins/bmad/skills/bmad-agent-builder/scripts/generate-html-report.py b/plugins/bmad/skills/bmad-agent-builder/scripts/generate-html-report.py new file mode 100644 index 0000000..a8614db --- /dev/null +++ b/plugins/bmad/skills/bmad-agent-builder/scripts/generate-html-report.py @@ -0,0 +1,1002 @@ +# /// script +# requires-python = ">=3.9" +# /// + +#!/usr/bin/env python3 +""" +Generate an interactive HTML quality report from scanner temp JSON files. + +Reads all *-temp.json and *-prepass.json files from a quality scan output +directory, normalizes findings into a unified data model, and produces a +self-contained HTML report with: + - Collapsible sections with severity filter badges + - Per-item copy-prompt buttons + - Multi-select batch prompt generator + - Executive summary with severity counts + +Usage: + python3 generate-html-report.py {quality-report-dir} [--open] [--skill-path /path/to/skill] + +The --skill-path is embedded in the prompt context so generated prompts +reference the correct location. If omitted, it is read from the first +temp JSON that contains a skill_path field. +""" + +from __future__ import annotations + +import argparse +import json +import platform +import subprocess +import sys +from datetime import datetime, timezone +from pathlib import Path + + +# ============================================================================= +# Normalization — diverse scanner JSONs → unified item model +# ============================================================================= + +SEVERITY_RANK = { + 'critical': 0, 'high': 1, 'medium': 2, 'low': 3, + 'high-opportunity': 1, 'medium-opportunity': 2, 'low-opportunity': 3, + 'note': 4, 'strength': 5, 'suggestion': 4, 'info': 5, +} + +# Map scanner names to report sections +SCANNER_SECTIONS = { + 'workflow-integrity': 'structural', + 'structure': 'structure-capabilities', + 'prompt-craft': 'prompt-craft', + 'execution-efficiency': 'efficiency', + 'skill-cohesion': 'cohesion', + 'agent-cohesion': 'cohesion', + 'path-standards': 'quality', + 'scripts': 'scripts', + 'script-opportunities': 'script-opportunities', + 'enhancement-opportunities': 'creative', +} + +SECTION_LABELS = { + 'structural': 'Structural', + 'structure-capabilities': 'Structure & Capabilities', + 'prompt-craft': 'Prompt Craft', + 'efficiency': 'Efficiency', + 'cohesion': 'Cohesion', + 'quality': 'Path & Script Standards', + 'scripts': 'Scripts', + 'script-opportunities': 'Script Opportunities', + 'creative': 'Creative & Enhancements', +} + + +def _coalesce(*values) -> str: + """Return the first truthy string value, or empty string.""" + for v in values: + if v and isinstance(v, str) and v.strip() and v.strip() not in ('N/A', 'n/a', 'None'): + return v.strip() + return '' + + +def _norm_severity(sev: str) -> str: + """Normalize severity to lowercase, handle variants.""" + if not sev: + return 'low' + s = sev.strip().lower() + # Map common variants + return { + 'high-opportunity': 'high-opportunity', + 'medium-opportunity': 'medium-opportunity', + 'low-opportunity': 'low-opportunity', + }.get(s, s) + + +def normalize_finding(f: dict, scanner: str, idx: int) -> dict: + """ + Normalize a single finding/issue dict into the unified item model. + + Handles all known field name variants across scanners: + Title: issue | title | description (fallback) + Desc: description | rationale | observation | insight | scenario | + current_behavior | current_pattern | context | nuance + Action: fix | recommendation | suggestion | suggested_approach | + efficient_alternative | script_alternative + File: file | location | current_location + Line: line | lines + Cat: category | dimension + Impact: user_impact | impact | estimated_savings | estimated_token_savings + """ + sev = _norm_severity(f.get('severity', 'low')) + section = SCANNER_SECTIONS.get(scanner, 'other') + + # Determine item type from severity + if sev in ('strength', 'note') or f.get('category') == 'strength': + item_type = 'strength' + action_type = 'none' + selectable = False + elif sev.endswith('-opportunity'): + item_type = 'enhancement' + action_type = 'enhance' + selectable = True + elif f.get('category') == 'suggestion' or sev == 'suggestion': + item_type = 'suggestion' + action_type = 'refactor' + selectable = True + else: + item_type = 'issue' + action_type = 'fix' + selectable = True + + # --- Title: prefer 'title', fall back to old field names --- + title = _coalesce( + f.get('title'), + f.get('issue'), + _truncate(f.get('scenario', ''), 150), + _truncate(f.get('current_behavior', ''), 150), + _truncate(f.get('description', ''), 150), + f.get('observation', ''), + ) + if not title: + title = f.get('id', 'Finding') + + # --- Detail/description: prefer 'detail', fall back to old field names --- + description = _coalesce(f.get('detail')) + if not description: + # Backward compat: coalesce old field names + desc_candidates = [] + for key in ('description', 'rationale', 'observation', 'insight', 'scenario', + 'current_behavior', 'current_pattern', 'context', 'nuance', + 'assessment'): + v = f.get(key) + if v and isinstance(v, str) and v.strip() and v != title: + desc_candidates.append(v.strip()) + description = ' '.join(desc_candidates) if desc_candidates else '' + + # --- Action: prefer 'action', fall back to old field names --- + action = _coalesce( + f.get('action'), + f.get('fix'), + f.get('recommendation'), + f.get('suggestion'), + f.get('suggested_approach'), + f.get('efficient_alternative'), + f.get('script_alternative'), + ) + + # --- File reference --- + file_ref = _coalesce( + f.get('file'), + f.get('location'), + f.get('current_location'), + ) + + # --- Line reference --- + line = f.get('line') + if line is None: + lines_str = f.get('lines') + if lines_str: + line = str(lines_str) + + # --- Category --- + category = _coalesce( + f.get('category'), + f.get('dimension'), + ) + + # --- Impact (backward compat only - new schema folds into detail) --- + impact = _coalesce( + f.get('user_impact'), + f.get('impact'), + f.get('estimated_savings'), + str(f.get('estimated_token_savings', '')) if f.get('estimated_token_savings') else '', + ) + + # --- Extra fields for specific scanners --- + extra = {} + if scanner == 'script-opportunities': + action_type = 'create-script' + for k in ('determinism_confidence', 'implementation_complexity', + 'language', 'could_be_prepass', 'reusable_across_skills'): + if k in f: + extra[k] = f[k] + + # Use scanner-provided id if available + item_id = f.get('id', f'{scanner}-{idx:03d}') + + return { + 'id': item_id, + 'scanner': scanner, + 'section': section, + 'type': item_type, + 'severity': sev, + 'rank': SEVERITY_RANK.get(sev, 3), + 'category': category, + 'file': file_ref, + 'line': line, + 'title': title, + 'description': description, + 'action': action, + 'impact': impact, + 'extra': extra, + 'selectable': selectable, + 'action_type': action_type, + } + + +def _truncate(text: str, max_len: int) -> str: + """Truncate text to max_len, breaking at sentence boundary if possible.""" + if not text: + return '' + text = text.strip() + if len(text) <= max_len: + return text + # Try to break at sentence boundary + for end in ('. ', '.\n', ' — ', '; '): + pos = text.find(end) + if 0 < pos < max_len: + return text[:pos + 1].strip() + return text[:max_len].strip() + '...' + + +def normalize_scanner(data: dict) -> tuple[list[dict], dict]: + """ + Normalize a full scanner JSON into (items, meta). + Returns list of normalized items + dict of meta/assessment data. + Handles all known scanner output variants. + """ + scanner = data.get('scanner', 'unknown') + items = [] + meta = {} + + # New schema: findings[]. Backward compat: issues[] or findings[] + findings = data.get('findings') or data.get('issues') or [] + for idx, f in enumerate(findings): + items.append(normalize_finding(f, scanner, idx)) + + # Backward compat: opportunities[] (execution-efficiency had separate array) + for idx, opp in enumerate(data.get('opportunities', []), start=len(findings)): + opp_item = normalize_finding(opp, scanner, idx) + opp_item['type'] = 'enhancement' + opp_item['action_type'] = 'enhance' + opp_item['selectable'] = True + items.append(opp_item) + + # Backward compat: strengths[] (old cohesion scanners — plain strings) + for idx, s in enumerate(data.get('strengths', [])): + text = s if isinstance(s, str) else (s.get('title', '') if isinstance(s, dict) else str(s)) + desc = '' if isinstance(s, str) else (s.get('description', s.get('detail', '')) if isinstance(s, dict) else '') + items.append({ + 'id': f'{scanner}-str-{idx:03d}', + 'scanner': scanner, + 'section': SCANNER_SECTIONS.get(scanner, 'cohesion'), + 'type': 'strength', + 'severity': 'strength', + 'rank': 5, + 'category': 'strength', + 'file': '', + 'line': None, + 'title': text, + 'description': desc, + 'action': '', + 'impact': '', + 'extra': {}, + 'selectable': False, + 'action_type': 'none', + }) + + # Backward compat: creative_suggestions[] (old cohesion scanners) + for idx, cs in enumerate(data.get('creative_suggestions', [])): + if isinstance(cs, str): + cs_title, cs_desc = cs, '' + else: + cs_title = _coalesce(cs.get('title'), cs.get('idea'), '') + cs_desc = _coalesce(cs.get('description'), cs.get('detail'), cs.get('rationale'), '') + items.append({ + 'id': cs.get('id', f'{scanner}-cs-{idx:03d}') if isinstance(cs, dict) else f'{scanner}-cs-{idx:03d}', + 'scanner': scanner, + 'section': SCANNER_SECTIONS.get(scanner, 'cohesion'), + 'type': 'suggestion', + 'severity': 'suggestion', + 'rank': 4, + 'category': cs.get('type', 'suggestion') if isinstance(cs, dict) else 'suggestion', + 'file': '', + 'line': None, + 'title': cs_title, + 'description': cs_desc, + 'action': cs_title, + 'impact': cs.get('estimated_impact', '') if isinstance(cs, dict) else '', + 'extra': {}, + 'selectable': True, + 'action_type': 'refactor', + }) + + # New schema: assessments{} contains all structured analysis + # Backward compat: also collect from top-level keys + if 'assessments' in data: + meta.update(data['assessments']) + + # Backward compat: collect meta from top-level keys + skip_keys = {'scanner', 'script', 'version', 'skill_path', 'agent_path', + 'timestamp', 'scan_date', 'status', 'issues', 'findings', + 'strengths', 'creative_suggestions', 'opportunities', 'assessments'} + for key, val in data.items(): + if key not in skip_keys and key not in meta: + meta[key] = val + + return items, meta + + +def build_journeys(data: dict) -> list[dict]: + """ + Extract user journey data from enhancement-opportunities scanner. + Handles two formats: + - Array of objects: [{archetype, journey_summary, friction_points, bright_spots}] + - Object keyed by persona: {first_timer: {entry_friction, mid_flow_resilience, exit_satisfaction}} + """ + journeys_raw = data.get('user_journeys') + if not journeys_raw: + return [] + + # Format 1: already a list — normalize field names + if isinstance(journeys_raw, list): + normalized = [] + for j in journeys_raw: + if isinstance(j, dict): + normalized.append({ + 'archetype': j.get('archetype', 'unknown'), + 'journey_summary': j.get('summary', j.get('journey_summary', '')), + 'friction_points': j.get('friction_points', []), + 'bright_spots': j.get('bright_spots', []), + }) + else: + normalized.append(j) + return normalized + + # Format 2: object keyed by persona name + if isinstance(journeys_raw, dict): + result = [] + for persona, details in journeys_raw.items(): + if isinstance(details, dict): + # Convert the dict-based format to the expected format + journey = { + 'archetype': persona.replace('_', ' ').title(), + 'journey_summary': '', + 'friction_points': [], + 'bright_spots': [], + } + # Map known sub-keys to friction/bright spots + for key, val in details.items(): + if isinstance(val, str): + # Heuristic: negative-sounding keys → friction, positive → bright + if any(neg in key.lower() for neg in ('friction', 'issue', 'problem', 'gap', 'pain')): + journey['friction_points'].append(val) + elif any(pos in key.lower() for pos in ('bright', 'strength', 'satisfaction', 'delight')): + journey['bright_spots'].append(val) + else: + # Neutral keys — include as summary parts + if journey['journey_summary']: + journey['journey_summary'] += f' | {key}: {val}' + else: + journey['journey_summary'] = f'{key}: {val}' + elif isinstance(val, list): + for item in val: + if isinstance(item, str): + journey['friction_points'].append(item) + # Build summary from all fields if not yet set + if not journey['journey_summary']: + parts = [] + for k, v in details.items(): + if isinstance(v, str): + parts.append(f'**{k.replace("_", " ").title()}:** {v}') + journey['journey_summary'] = ' | '.join(parts) if parts else str(details) + result.append(journey) + elif isinstance(details, str): + result.append({ + 'archetype': persona.replace('_', ' ').title(), + 'journey_summary': details, + 'friction_points': [], + 'bright_spots': [], + }) + return result + + return [] + + +# ============================================================================= +# Report Data Assembly +# ============================================================================= + +def load_report_data(report_dir: Path, skill_path: str | None) -> dict: + """Load all temp/prepass JSONs and assemble normalized report data.""" + all_items = [] + all_meta = {} + journeys = [] + detected_skill_path = skill_path + + # Read all JSON files + json_files = sorted(report_dir.glob('*.json')) + for jf in json_files: + try: + data = json.loads(jf.read_text(encoding='utf-8')) + except (json.JSONDecodeError, OSError): + continue + + if not isinstance(data, dict): + continue + + scanner = data.get('scanner', jf.stem.replace('-temp', '').replace('-prepass', '')) + + # Detect skill path from scanner data + if not detected_skill_path: + detected_skill_path = data.get('skill_path') or data.get('agent_path') + + # Only normalize temp files (not prepass) + if '-temp' in jf.name or jf.name in ('path-standards-temp.json', 'scripts-temp.json'): + items, meta = normalize_scanner(data) + all_items.extend(items) + all_meta[scanner] = meta + + if scanner == 'enhancement-opportunities': + journeys = build_journeys(data) + elif '-prepass' in jf.name: + all_meta[f'prepass-{scanner}'] = data + + # Sort items: severity rank first, then section + all_items.sort(key=lambda x: (x['rank'], x['section'])) + + # Build severity counts + counts = {'critical': 0, 'high': 0, 'medium': 0, 'low': 0} + for item in all_items: + if item['type'] == 'issue' and item['severity'] in counts: + counts[item['severity']] += 1 + + enhancement_count = sum(1 for i in all_items if i['type'] == 'enhancement') + strength_count = sum(1 for i in all_items if i['type'] == 'strength') + total_issues = sum(counts.values()) + + # Quality grade + if counts['critical'] > 0: + grade = 'Poor' + elif counts['high'] > 2: + grade = 'Fair' + elif counts['high'] > 0 or counts['medium'] > 5: + grade = 'Good' + else: + grade = 'Excellent' + + # Extract assessments for display + assessments = {} + for scanner_key, meta in all_meta.items(): + for akey in ('cohesion_analysis', 'autonomous_assessment', 'skill_understanding', + 'agent_identity', 'skill_identity', 'prompt_health', + 'skillmd_assessment', 'top_insights'): + if akey in meta: + assessments[akey] = meta[akey] + if 'summary' in meta: + s = meta['summary'] + if 'craft_assessment' in s: + assessments['craft_assessment'] = s['craft_assessment'] + if 'overall_cohesion' in s: + assessments['overall_cohesion'] = s['overall_cohesion'] + + # Skill name from path + sp = detected_skill_path or str(report_dir) + skill_name = Path(sp).name + + return { + 'meta': { + 'skill_name': skill_name, + 'skill_path': detected_skill_path or '', + 'timestamp': datetime.now(timezone.utc).isoformat(), + 'scanner_count': len([f for f in json_files if '-temp' in f.name]), + 'report_dir': str(report_dir), + }, + 'executive_summary': { + 'total_issues': total_issues, + 'counts': counts, + 'enhancement_count': enhancement_count, + 'strength_count': strength_count, + 'grade': grade, + 'craft_assessment': assessments.get('craft_assessment', ''), + 'overall_cohesion': assessments.get('overall_cohesion', ''), + }, + 'items': all_items, + 'journeys': journeys, + 'assessments': assessments, + 'section_labels': SECTION_LABELS, + } + + +# ============================================================================= +# HTML Generation +# ============================================================================= + +HTML_TEMPLATE = r""" + + + + +Quality Report: SKILL_NAME_PLACEHOLDER + + + + +

Quality Report:

+
+ +
+ +
+ +
+ + + + + + + +""" + + +def generate_html(report_data: dict) -> str: + """Inject report data into the HTML template.""" + data_json = json.dumps(report_data, indent=None, ensure_ascii=False) + # Embed the JSON as a script tag before the main script + data_tag = f'' + # Insert before the main + +""" + + +def generate_html(report_data: dict) -> str: + """Inject report data into the HTML template.""" + data_json = json.dumps(report_data, indent=None, ensure_ascii=False) + # Embed the JSON as a script tag before the main script + data_tag = f'' + # Insert before the main