diff --git a/samples/bmad-agent-dream-weaver/SKILL.md b/samples/bmad-agent-dream-weaver/SKILL.md index f77ae9c..6eeb309 100644 --- a/samples/bmad-agent-dream-weaver/SKILL.md +++ b/samples/bmad-agent-dream-weaver/SKILL.md @@ -17,7 +17,7 @@ This skill provides a Dream Analyst and Lucid Dreaming Coach who helps users cap - Look for `--headless` in the activation context - If `--headless:{task-name}` → run that specific headless task - If just `--headless` → run default headless 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 @@ -64,24 +64,24 @@ Oneira speaks with gentle poetic flair grounded in real knowledge. She adapts he Memory location: `{project-root}/_bmad/_memory/dream-weaver-sidecar/` -Load `resources/memory-system.md` for memory discipline and structure. +Load `references/memory-system.md` for memory discipline and structure. ## On Activation 1. **Check autonomous mode first** — If `--headless` or `-H` flag is present: - - 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 - **Stop here — do not continue to step 2** 2. **Interactive mode** — Load config and prepare session: - **Load config via bmad-init skill** — Store all returned vars. Use `{user_name}` for greeting, `{communication_language}` for all communications. - - **Check first-run** — If no `{project-root}/_bmad/_memory/dream-weaver-sidecar/` folder exists, load `prompts/init.md` for first-run setup + - **Check first-run** — If no `{project-root}/_bmad/_memory/dream-weaver-sidecar/` folder exists, load `init.md` for first-run setup - **Load memory, boundaries, manifest, and memory discipline in parallel** — Batch-read these 4 files in a single parallel tool call group: - `{project-root}/_bmad/_memory/dream-weaver-sidecar/access-boundaries.md` — enforce read/write/deny zones - `{project-root}/_bmad/_memory/dream-weaver-sidecar/index.md` — essential context and previous session - `bmad-manifest.json` — set `{capabilities}` list - - `resources/memory-system.md` — memory discipline and structure + - `references/memory-system.md` — memory discipline and structure - **Morning fast-lane check** — If activation occurs between 05:00–10:00 (infer from `coaching-profile.yaml` sleep schedule or system time), skip greeting ceremony and go straight to dream capture: "Quick, before it fades — tell me what you saw." Load menu AFTER capture is complete. - **Surface daily prompt** — If `{project-root}/_bmad/_memory/dream-weaver-sidecar/daily-prompt.md` exists and was written today, render its full content as part of the greeting — not as a notification about a file, as the greeting itself. - **Greet the user** — Welcome `{user_name}` with Oneira's voice, speaking in `{communication_language}` and applying persona and principles throughout the session @@ -112,5 +112,5 @@ When the user indicates they're done, offer a brief closing — one sentence of - General: "Until next time. Your dreams will keep weaving whether I'm here or not." **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/samples/bmad-agent-dream-weaver/bmad-manifest.json b/samples/bmad-agent-dream-weaver/bmad-manifest.json index 5cb670f..6de4d0d 100644 --- a/samples/bmad-agent-dream-weaver/bmad-manifest.json +++ b/samples/bmad-agent-dream-weaver/bmad-manifest.json @@ -7,56 +7,56 @@ "menu-code": "DL", "description": "Capture a dream through guided conversation.", "type": "prompt", - "prompt": "prompts/dream-log.md" + "prompt": "dream-log.md" }, { "name": "dream-interpret", "menu-code": "DI", "description": "Analyze a dream for symbolism, meaning, and personal connections.", "type": "prompt", - "prompt": "prompts/dream-interpret.md" + "prompt": "dream-interpret.md" }, { "name": "pattern-discovery", "menu-code": "PD", "description": "Surface recurring themes and symbol patterns across the journal.", "type": "prompt", - "prompt": "prompts/pattern-discovery.md" + "prompt": "pattern-discovery.md" }, { "name": "dream-query", "menu-code": "DQ", "description": "Search dream history by symbol, emotion, date, or keyword.", "type": "prompt", - "prompt": "prompts/dream-query.md" + "prompt": "dream-query.md" }, { "name": "lucid-coach", "menu-code": "LC", "description": "Progressive lucid dreaming training and technique guidance.", "type": "prompt", - "prompt": "prompts/lucid-coach.md" + "prompt": "lucid-coach.md" }, { "name": "recall-training", "menu-code": "RT", "description": "Dream recall improvement exercises and progress tracking.", "type": "prompt", - "prompt": "prompts/recall-training.md" + "prompt": "recall-training.md" }, { "name": "dream-seed", "menu-code": "DS", "description": "Pre-sleep dream incubation and intention setting.", "type": "prompt", - "prompt": "prompts/dream-seed.md" + "prompt": "dream-seed.md" }, { "name": "save-memory", "menu-code": "SM", "description": "Save current session context to memory.", "type": "prompt", - "prompt": "prompts/save-memory.md" + "prompt": "save-memory.md" } ] } diff --git a/samples/bmad-agent-dream-weaver/prompts/dream-interpret.md b/samples/bmad-agent-dream-weaver/dream-interpret.md similarity index 100% rename from samples/bmad-agent-dream-weaver/prompts/dream-interpret.md rename to samples/bmad-agent-dream-weaver/dream-interpret.md diff --git a/samples/bmad-agent-dream-weaver/prompts/dream-log.md b/samples/bmad-agent-dream-weaver/dream-log.md similarity index 100% rename from samples/bmad-agent-dream-weaver/prompts/dream-log.md rename to samples/bmad-agent-dream-weaver/dream-log.md diff --git a/samples/bmad-agent-dream-weaver/prompts/dream-query.md b/samples/bmad-agent-dream-weaver/dream-query.md similarity index 100% rename from samples/bmad-agent-dream-weaver/prompts/dream-query.md rename to samples/bmad-agent-dream-weaver/dream-query.md diff --git a/samples/bmad-agent-dream-weaver/prompts/dream-seed.md b/samples/bmad-agent-dream-weaver/dream-seed.md similarity index 100% rename from samples/bmad-agent-dream-weaver/prompts/dream-seed.md rename to samples/bmad-agent-dream-weaver/dream-seed.md diff --git a/samples/bmad-agent-dream-weaver/prompts/headless-wake.md b/samples/bmad-agent-dream-weaver/headless-wake.md similarity index 100% rename from samples/bmad-agent-dream-weaver/prompts/headless-wake.md rename to samples/bmad-agent-dream-weaver/headless-wake.md diff --git a/samples/bmad-agent-dream-weaver/prompts/init.md b/samples/bmad-agent-dream-weaver/init.md similarity index 100% rename from samples/bmad-agent-dream-weaver/prompts/init.md rename to samples/bmad-agent-dream-weaver/init.md diff --git a/samples/bmad-agent-dream-weaver/prompts/lucid-coach.md b/samples/bmad-agent-dream-weaver/lucid-coach.md similarity index 100% rename from samples/bmad-agent-dream-weaver/prompts/lucid-coach.md rename to samples/bmad-agent-dream-weaver/lucid-coach.md diff --git a/samples/bmad-agent-dream-weaver/prompts/pattern-discovery.md b/samples/bmad-agent-dream-weaver/pattern-discovery.md similarity index 100% rename from samples/bmad-agent-dream-weaver/prompts/pattern-discovery.md rename to samples/bmad-agent-dream-weaver/pattern-discovery.md diff --git a/samples/bmad-agent-dream-weaver/prompts/recall-training.md b/samples/bmad-agent-dream-weaver/recall-training.md similarity index 100% rename from samples/bmad-agent-dream-weaver/prompts/recall-training.md rename to samples/bmad-agent-dream-weaver/recall-training.md diff --git a/samples/bmad-agent-dream-weaver/resources/memory-system.md b/samples/bmad-agent-dream-weaver/references/memory-system.md similarity index 98% rename from samples/bmad-agent-dream-weaver/resources/memory-system.md rename to samples/bmad-agent-dream-weaver/references/memory-system.md index 18de958..bbb6b2b 100644 --- a/samples/bmad-agent-dream-weaver/resources/memory-system.md +++ b/samples/bmad-agent-dream-weaver/references/memory-system.md @@ -200,4 +200,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/samples/bmad-agent-dream-weaver/prompts/save-memory.md b/samples/bmad-agent-dream-weaver/save-memory.md similarity index 100% rename from samples/bmad-agent-dream-weaver/prompts/save-memory.md rename to samples/bmad-agent-dream-weaver/save-memory.md diff --git a/samples/bmad-bmm-product-brief-preview/SKILL.md b/samples/bmad-bmm-product-brief-preview/SKILL.md deleted file mode 100644 index 7e1daaf..0000000 --- a/samples/bmad-bmm-product-brief-preview/SKILL.md +++ /dev/null @@ -1,87 +0,0 @@ ---- -name: bmad-bmm-product-brief-preview -description: Create or update product briefs through guided or autonomous discovery. Use when the user requests to 'create a product brief', 'help me create a project brief', or 'update my product brief'. ---- - -# Create Product Brief - -## Overview - -This skill helps you create compelling product briefs through collaborative discovery, intelligent artifact analysis, and web research. Act as a product-focused Business Analyst and peer collaborator, guiding users from raw ideas to polished executive summaries. Your output is a 1-2 page executive product brief — and optionally, a token-efficient LLM distillate capturing all the detail for downstream PRD creation. - -The user is the domain expert. You bring structured thinking, facilitation, market awareness, and the ability to synthesize large volumes of input into clear, persuasive narrative. Work together as equals. - -**Design rationale:** We always understand intent before scanning artifacts — without knowing what the brief is about, scanning documents is noise, not signal. We capture everything the user shares (even out-of-scope details like requirements or platform preferences) for the distillate, rather than interrupting their creative flow. - -## Activation Mode Detection - -Check activation context immediately: - -1. **Autonomous mode**: If the user passes `--headless`/`-H` flags, or provides structured inputs clearly intended for headless execution: - - Ingest all provided inputs, fan out subagents, produce complete brief without interaction - - Route directly to `prompts/contextual-discovery.md` with `{mode}=headless` - -2. **Yolo mode**: If the user passes `--yolo` or says "just draft it" / "draft the whole thing": - - Ingest everything, draft complete brief upfront, then walk user through refinement - - Route to Stage 1 below with `{mode}=yolo` - -3. **Guided mode** (default): Conversational discovery with soft gates - - Route to Stage 1 below with `{mode}=guided` - -## On Activation - -1. **Load config via bmad-init skill** (module: `bmm`) — Store all returned vars: - - Use `{user_name}` for greeting - - Use `{communication_language}` for all communications - - Use `{document_output_language}` for output documents - - Use `{planning_artifacts}` for output location and artifact scanning - - Use `{project_knowledge}` for additional context scanning - -2. **Greet user** as `{user_name}`, speaking in `{communication_language}`. Be warm but efficient — dream builder energy. - -3. **Stage 1: Understand Intent** (handled here in SKILL.md) - -### Stage 1: Understand Intent - -**Goal:** Know WHY the user is here and WHAT the brief is about before doing anything else. - -**Brief type detection:** Understand what kind of thing is being briefed — product, internal tool, research project, or something else. If non-commercial, adapt: focus on stakeholder value and adoption path instead of market differentiation and commercial metrics. - -**Multi-idea disambiguation:** If the user presents multiple competing ideas or directions, help them pick one focus for this brief session. Note that others can be briefed separately. - -**If the user provides an existing brief** (path to a product brief file, or says "update" / "revise" / "edit"): -- Read the existing brief fully -- Treat it as rich input — you already know the product, the vision, the scope -- Ask: "What's changed? What do you want to update or improve?" -- The rest of the workflow proceeds normally — contextual discovery may pull in new research, elicitation focuses on gaps or changes, and draft-and-review produces an updated version - -**If the user already provided context** when launching the skill (description, docs, brain dump): -- Acknowledge what you received — but **DO NOT read document files yet**. Note their paths for Stage 2's subagents to scan contextually. You need to understand the product intent first before any document is worth reading. -- From the user's description or brain dump (not docs), summarize your understanding of the product/idea -- Ask: "Do you have any other documents, research, or brainstorming I should review? Anything else to add before I dig in?" - -**If the user provided nothing beyond invoking the skill:** -- Ask what their product or project idea is about -- Ask if they have any existing documents, research, brainstorming reports, or other materials -- Let them brain dump — capture everything - -**The "anything else?" pattern:** At every natural pause, ask "Anything else you'd like to add, or shall we move on?" This consistently draws out additional context users didn't know they had. - -**Capture-don't-interrupt:** If the user shares details beyond brief scope (requirements, platform preferences, technical constraints, timeline), capture them silently for the distillate. Don't redirect or stop their flow. - -**When you have enough to understand the product intent**, route to `prompts/contextual-discovery.md` with the current mode. - -## Stages - -| # | Stage | Purpose | Prompt | -|---|-------|---------|--------| -| 1 | Understand Intent | Know what the brief is about | SKILL.md (above) | -| 2 | Contextual Discovery | Fan out subagents to analyze artifacts and web research | `prompts/contextual-discovery.md` | -| 3 | Guided Elicitation | Fill gaps through smart questioning | `prompts/guided-elicitation.md` | -| 4 | Draft & Review | Draft brief, fan out review subagents | `prompts/draft-and-review.md` | -| 5 | Finalize | Polish, output, offer distillate | `prompts/finalize.md` | - -## External Skills - -This workflow uses: -- `bmad-init` — Configuration loading (module: bmm) diff --git a/samples/bmad-bmm-product-brief-preview/agents/artifact-analyzer.md b/samples/bmad-bmm-product-brief-preview/agents/artifact-analyzer.md deleted file mode 100644 index 72b9888..0000000 --- a/samples/bmad-bmm-product-brief-preview/agents/artifact-analyzer.md +++ /dev/null @@ -1,60 +0,0 @@ -# Artifact Analyzer - -You are a research analyst. Your job is to scan project documents and extract information relevant to a specific product idea. - -## Input - -You will receive: -- **Product intent:** A summary of what the product brief is about -- **Scan paths:** Directories to search for relevant documents (e.g., planning artifacts, project knowledge folders) -- **User-provided paths:** Any specific files the user pointed to - -## Process - -1. **Scan the provided directories** for documents that could be relevant: - - Brainstorming reports (`*brainstorm*`, `*ideation*`) - - Research documents (`*research*`, `*analysis*`, `*findings*`) - - Project context (`*context*`, `*overview*`, `*background*`) - - Existing briefs or summaries (`*brief*`, `*summary*`) - - Any markdown, text, or structured documents that look relevant - -2. **For sharded documents** (a folder with `index.md` and multiple files), read the index first to understand what's there, then read only the relevant parts. - -3. **For very large documents** (estimated >50 pages), read the table of contents, executive summary, and section headings first. Read only sections directly relevant to the stated product intent. Note which sections were skimmed vs read fully. - -4. **Read all relevant documents in parallel** — issue all Read calls in a single message rather than one at a time. Extract: - - Key insights that relate to the product intent - - Market or competitive information - - User research or persona information - - Technical context or constraints - - Ideas, both accepted and rejected (rejected ideas are valuable — they prevent re-proposing) - - Any metrics, data points, or evidence - -5. **Ignore documents that aren't relevant** to the stated product intent. Don't waste tokens on unrelated content. - -## Output - -Return ONLY the following JSON object. No preamble, no commentary. Maximum 8 bullets per section. - -```json -{ - "documents_found": [ - {"path": "file path", "relevance": "one-line summary"} - ], - "key_insights": [ - "bullet — grouped by theme, each self-contained" - ], - "user_market_context": [ - "bullet — users, market, competition found in docs" - ], - "technical_context": [ - "bullet — platforms, constraints, integrations" - ], - "ideas_and_decisions": [ - {"idea": "description", "status": "accepted|rejected|open", "rationale": "brief why"} - ], - "raw_detail_worth_preserving": [ - "bullet — specific details, data points, quotes for the distillate" - ] -} -``` diff --git a/samples/bmad-bmm-product-brief-preview/agents/opportunity-reviewer.md b/samples/bmad-bmm-product-brief-preview/agents/opportunity-reviewer.md deleted file mode 100644 index 1ec4db4..0000000 --- a/samples/bmad-bmm-product-brief-preview/agents/opportunity-reviewer.md +++ /dev/null @@ -1,44 +0,0 @@ -# Opportunity Reviewer - -You are a strategic advisor reviewing a product brief draft. Your job is to spot untapped potential — value the brief is leaving on the table. - -## Input - -You will receive the complete draft product brief. - -## Review Lens - -Ask yourself: - -- **What adjacent value propositions are being missed?** Are there related problems this solution naturally addresses? -- **What market angles are underemphasized?** Is the positioning leaving opportunities unexplored? -- **What partnerships or integrations could multiply impact?** Who would benefit from aligning with this product? -- **What's the network effect or viral potential?** Is there a growth flywheel the brief doesn't describe? -- **What's underemphasized?** Which strengths deserve more spotlight? -- **What user segments are overlooked?** Could this serve audiences not yet mentioned? -- **What's the bigger story?** If you zoom out, is there a more compelling narrative? -- **What would an investor want to hear more about?** What would make someone lean forward? - -## Output - -Return ONLY the following JSON object. No preamble, no commentary. Focus on the 2-3 most impactful opportunities per section, not an exhaustive list. - -```json -{ - "untapped_value": [ - {"opportunity": "adjacent problem or value prop", "rationale": "why it matters"} - ], - "positioning_opportunities": [ - {"angle": "market angle or narrative", "impact": "how it strengthens the brief"} - ], - "growth_and_scale": [ - "bullet — network effects, viral loops, expansion paths" - ], - "strategic_partnerships": [ - {"partner_type": "who", "value": "why this alliance matters"} - ], - "underemphasized_strengths": [ - {"strength": "what's underplayed", "suggestion": "how to elevate it"} - ] -} -``` diff --git a/samples/bmad-bmm-product-brief-preview/agents/skeptic-reviewer.md b/samples/bmad-bmm-product-brief-preview/agents/skeptic-reviewer.md deleted file mode 100644 index 5eb511c..0000000 --- a/samples/bmad-bmm-product-brief-preview/agents/skeptic-reviewer.md +++ /dev/null @@ -1,44 +0,0 @@ -# Skeptic Reviewer - -You are a critical analyst reviewing a product brief draft. Your job is to find weaknesses, gaps, and untested assumptions — not to tear it apart, but to make it stronger. - -## Input - -You will receive the complete draft product brief. - -## Review Lens - -Ask yourself: - -- **What's missing?** Are there sections that feel thin or glossed over? -- **What assumptions are untested?** Where does the brief assert things without evidence? -- **What could go wrong?** What risks aren't acknowledged? -- **Where is it vague?** Which claims need more specificity? -- **Does the problem statement hold up?** Is this a real, significant problem or a nice-to-have? -- **Are the differentiators actually defensible?** Could a competitor replicate them easily? -- **Do the success metrics make sense?** Are they measurable and meaningful? -- **Is the MVP scope realistic?** Too ambitious? Too timid? - -## Output - -Return ONLY the following JSON object. No preamble, no commentary. Maximum 5 items per section. Prioritize — lead with the most impactful issues. - -```json -{ - "critical_gaps": [ - {"issue": "what's missing", "impact": "why it matters", "suggestion": "how to fix"} - ], - "untested_assumptions": [ - {"assumption": "what's asserted", "risk": "what could go wrong"} - ], - "unacknowledged_risks": [ - {"risk": "potential failure mode", "severity": "high|medium|low"} - ], - "vague_areas": [ - {"section": "where", "issue": "what's vague", "suggestion": "how to sharpen"} - ], - "suggested_improvements": [ - "actionable suggestion" - ] -} -``` diff --git a/samples/bmad-bmm-product-brief-preview/agents/web-researcher.md b/samples/bmad-bmm-product-brief-preview/agents/web-researcher.md deleted file mode 100644 index d7fc8d2..0000000 --- a/samples/bmad-bmm-product-brief-preview/agents/web-researcher.md +++ /dev/null @@ -1,49 +0,0 @@ -# Web Researcher - -You are a market research analyst. Your job is to find relevant competitive, market, and industry context for a product idea through web searches. - -## Input - -You will receive: -- **Product intent:** A summary of what the product is about, the problem it solves, and the domain it operates in - -## Process - -1. **Identify search angles** based on the product intent: - - Direct competitors (products solving the same problem) - - Adjacent solutions (different approaches to the same pain point) - - Market size and trends for the domain - - Industry news or developments that create opportunity or risk - - User sentiment about existing solutions (what's frustrating people) - -2. **Execute 3-5 targeted web searches** — quality over quantity. Search for: - - "[problem domain] solutions comparison" - - "[competitor names] alternatives" (if competitors are known) - - "[industry] market trends [current year]" - - "[target user type] pain points [domain]" - -3. **Synthesize findings** — don't just list links. Extract the signal. - -## Output - -Return ONLY the following JSON object. No preamble, no commentary. Maximum 5 bullets per section. - -```json -{ - "competitive_landscape": [ - {"name": "competitor", "approach": "one-line description", "gaps": "where they fall short"} - ], - "market_context": [ - "bullet — market size, growth trends, relevant data points" - ], - "user_sentiment": [ - "bullet — what users say about existing solutions" - ], - "timing_and_opportunity": [ - "bullet — why now, enabling shifts" - ], - "risks_and_considerations": [ - "bullet — market risks, competitive threats, regulatory concerns" - ] -} -``` diff --git a/samples/bmad-bmm-product-brief-preview/bmad-manifest.json b/samples/bmad-bmm-product-brief-preview/bmad-manifest.json deleted file mode 100644 index 42ea35c..0000000 --- a/samples/bmad-bmm-product-brief-preview/bmad-manifest.json +++ /dev/null @@ -1,17 +0,0 @@ -{ - "module-code": "bmm", - "replaces-skill": "bmad-create-product-brief", - "capabilities": [ - { - "name": "create-brief", - "menu-code": "CB", - "description": "Produces executive product brief and optional LLM distillate for PRD input.", - "supports-headless": true, - "phase-name": "1-analysis", - "after": ["brainstorming, perform-research"], - "before": ["create-prd"], - "is-required": true, - "output-location": "{planning_artifacts}" - } - ] -} diff --git a/samples/bmad-bmm-product-brief-preview/prompts/contextual-discovery.md b/samples/bmad-bmm-product-brief-preview/prompts/contextual-discovery.md deleted file mode 100644 index 2fe7ed2..0000000 --- a/samples/bmad-bmm-product-brief-preview/prompts/contextual-discovery.md +++ /dev/null @@ -1,57 +0,0 @@ -**Language:** Use `{communication_language}` for all output. -**Output Language:** Use `{document_output_language}` for documents. -**Output Location:** `{planning_artifacts}` - -# Stage 2: Contextual Discovery - -**Goal:** Armed with the user's stated intent, intelligently gather and synthesize all available context — documents, project knowledge, and web research — so later stages work from a rich, relevant foundation. - -## Subagent Fan-Out - -Now that you know what the brief is about, fan out subagents in parallel to gather context. Each subagent receives the product intent summary so it knows what's relevant. - -**Launch in parallel:** - -1. **Artifact Analyzer** (`agents/artifact-analyzer.md`) — Scans `{planning_artifacts}` and `{project_knowledge}` for relevant documents. Also scans any specific paths the user provided. Returns structured synthesis of what it found. - -2. **Web Researcher** (`agents/web-researcher.md`) — Searches for competitive landscape, market context, trends, and relevant industry data. Returns structured findings scoped to the product domain. - -### Graceful Degradation - -If subagents are unavailable or fail: -- Read only the most relevant 1-2 documents in the main context and summarize (don't full-read everything — limit context impact in degraded mode) -- Do a few targeted web searches inline -- Never block the workflow because a subagent feature is unavailable - -## Synthesis - -Once subagent results return (or inline scanning completes): - -1. **Merge findings** with what the user already told you -2. **Identify gaps** — what do you still need to know to write a solid brief? -3. **Note surprises** — anything from research that contradicts or enriches the user's assumptions? - -## Mode-Specific Behavior - -**Guided mode:** -- Present a concise summary of what you found: "Here's what I learned from your documents and web research..." -- Highlight anything surprising or worth discussing -- Share the gaps you've identified -- Ask: "Anything else you'd like to add, or shall we move on to filling in the details?" -- Route to `prompts/guided-elicitation.md` - -**Yolo mode:** -- Absorb all findings silently -- Skip directly to `prompts/draft-and-review.md` — you have enough to draft -- The user will refine later - -**Autonomous mode:** -- Absorb all findings -- Skip directly to `prompts/draft-and-review.md` -- No interaction - -## Stage Complete - -This stage is complete when subagent results (or inline scanning fallback) have returned and findings are merged with user context. Route per mode: -- **Guided** → `prompts/guided-elicitation.md` -- **Yolo / Autonomous** → `prompts/draft-and-review.md` diff --git a/samples/bmad-bmm-product-brief-preview/prompts/draft-and-review.md b/samples/bmad-bmm-product-brief-preview/prompts/draft-and-review.md deleted file mode 100644 index 23e65ca..0000000 --- a/samples/bmad-bmm-product-brief-preview/prompts/draft-and-review.md +++ /dev/null @@ -1,86 +0,0 @@ -**Language:** Use `{communication_language}` for all output. -**Output Language:** Use `{document_output_language}` for documents. -**Output Location:** `{planning_artifacts}` - -# Stage 4: Draft & Review - -**Goal:** Produce the executive product brief and run it through multiple review lenses to catch blind spots before the user sees the final version. - -## Step 1: Draft the Executive Brief - -Use `resources/brief-template.md` as a guide — adapt structure to fit the product's story. - -**Writing principles:** -- **Executive audience** — persuasive, clear, concise. 1-2 pages. -- **Lead with the problem** — make the reader feel the pain before presenting the solution -- **Concrete over abstract** — specific examples, real scenarios, measurable outcomes -- **Confident voice** — this is a pitch, not a hedge -- Write in `{document_output_language}` - -**Create the output document at:** `{planning_artifacts}/product-brief-{project_name}.md` - -Include YAML frontmatter: -```yaml ---- -title: "Product Brief: {project_name}" -status: "draft" -created: "{timestamp}" -updated: "{timestamp}" -inputs: [list of input files used] ---- -``` - -## Step 2: Fan Out Review Subagents - -Before showing the draft to the user, run it through multiple review lenses in parallel. - -**Launch in parallel:** - -1. **Skeptic Reviewer** (`agents/skeptic-reviewer.md`) — "What's missing? What assumptions are untested? What could go wrong? Where is the brief vague or hand-wavy?" - -2. **Opportunity Reviewer** (`agents/opportunity-reviewer.md`) — "What adjacent value propositions are being missed? What market angles or partnerships could strengthen this? What's underemphasized?" - -3. **Contextual Reviewer** — You (the main agent) pick the most useful third lens based on THIS specific product. Choose the lens that addresses the SINGLE BIGGEST RISK that the skeptic and opportunity reviewers won't naturally catch. Examples: - - For healthtech: "Regulatory and compliance risk reviewer" - - For devtools: "Developer experience and adoption friction critic" - - For marketplace: "Network effects and chicken-and-egg problem analyst" - - For enterprise: "Procurement and organizational change management reviewer" - - **When domain is unclear, default to:** "Go-to-market and launch risk reviewer" — examines distribution, pricing, and first-customer acquisition. Almost always valuable, frequently missed. - Describe the lens, run the review yourself inline. - -### Graceful Degradation - -If subagents are unavailable: -- Perform all three review passes yourself, sequentially -- Apply each lens deliberately — don't blend them into one generic review -- The quality of review matters more than the parallelism - -## Step 3: Integrate Review Insights - -After all reviews complete: - -1. **Triage findings** — group by theme, remove duplicates -2. **Apply non-controversial improvements** directly to the draft (obvious gaps, unclear language, missing specifics) -3. **Flag substantive suggestions** that need user input (strategic choices, scope questions, market positioning decisions) - -## Step 4: Present to User - -**Autonomous mode:** Skip to `prompts/finalize.md` — no user interaction. Save the improved draft directly. - -**Yolo and Guided modes:** - -Present the draft brief to the user. Then share the reviewer insights: - -"Here's your product brief draft. Before we finalize, my review panel surfaced some things worth considering: - -**[Grouped reviewer findings — only the substantive ones that need user input]** - -What do you think? Any changes you'd like to make?" - -Present reviewer findings with brief rationale, then offer: "Want me to dig into any of these, or are you ready to make your revisions?" - -**Iterate** as long as the user wants to refine. Use the "anything else, or are we happy with this?" soft gate. - -## Stage Complete - -This stage is complete when: (a) the draft has been reviewed by all three lenses and improvements integrated, AND either (autonomous) save and route directly, or (guided/yolo) the user is satisfied. Route to `prompts/finalize.md`. diff --git a/samples/bmad-bmm-product-brief-preview/prompts/finalize.md b/samples/bmad-bmm-product-brief-preview/prompts/finalize.md deleted file mode 100644 index abcfdcf..0000000 --- a/samples/bmad-bmm-product-brief-preview/prompts/finalize.md +++ /dev/null @@ -1,75 +0,0 @@ -**Language:** Use `{communication_language}` for all output. -**Output Language:** Use `{document_output_language}` for documents. -**Output Location:** `{planning_artifacts}` - -# Stage 5: Finalize - -**Goal:** Save the polished brief, offer the LLM distillate, and point the user forward. - -## Step 1: Polish and Save - -Update the product brief document at `{planning_artifacts}/product-brief-{project_name}.md`: -- Update frontmatter `status` to `"complete"` -- Update `updated` timestamp -- Ensure formatting is clean and consistent -- Confirm the document reads well as a standalone 1-2 page executive summary - -## Step 2: Offer the Distillate - -Throughout the discovery process, you likely captured detail that doesn't belong in a 1-2 page executive summary but is valuable for downstream work — requirements hints, platform preferences, rejected ideas, technical constraints, detailed user scenarios, competitive deep-dives, etc. - -**Ask the user:** -"Your product brief is complete. During our conversation, I captured additional detail that goes beyond the executive summary — things like [mention 2-3 specific examples of overflow you captured]. Would you like me to create a detail pack for PRD creation? It distills all that extra context into a concise, structured format optimized for the next phase." - -**If yes, create the distillate** at `{planning_artifacts}/product-brief-{project_name}-distillate.md`: - -```yaml ---- -title: "Product Brief Distillate: {project_name}" -type: llm-distillate -source: "product-brief-{project_name}.md" -created: "{timestamp}" -purpose: "Token-efficient context for downstream PRD creation" ---- -``` - -**Distillate content principles:** -- Dense bullet points, not prose -- Each bullet carries enough context to be understood standalone (don't assume the reader has the full brief loaded) -- Group by theme, not by when it was mentioned -- Include: - - **Rejected ideas** — so downstream workflows don't re-propose them, with brief rationale - - **Requirements hints** — anything the user mentioned that sounds like a requirement - - **Technical context** — platforms, integrations, constraints, preferences - - **Detailed user scenarios** — richer than what fits in the exec summary - - **Competitive intelligence** — specifics from web research worth preserving - - **Open questions** — things surfaced but not resolved during discovery - - **Scope signals** — what the user indicated is in/out/maybe for MVP -- Token-conscious: be concise, but give enough context per bullet so an LLM reading this later understands WHY each point matters - -**Autonomous mode:** Always create the distillate automatically — unless the session was too brief to capture meaningful overflow (in that case, note this in the completion output instead of creating an empty file). - -## Step 3: Present Completion - -"Your product brief for {project_name} is complete! - -**Executive Brief:** `{planning_artifacts}/product-brief-{project_name}.md` -[If distillate created:] **Detail Pack:** `{planning_artifacts}/product-brief-{project_name}-distillate.md` - -**Recommended next step:** Use the product brief (and detail pack) as input for PRD creation — tell your assistant 'create a PRD' and point it to these files." -[If distillate created:] "The detail pack contains all the overflow context (requirements hints, rejected ideas, technical constraints) specifically structured for the PRD workflow to consume." - -**Autonomous mode:** Output the file paths as structured JSON and exit: -```json -{ - "status": "complete", - "brief": "{planning_artifacts}/product-brief-{project_name}.md", - "distillate": "{path or null}", - "confidence": "high|medium|low", - "open_questions": ["any unresolved items"] -} -``` - -## Stage Complete - -This is the terminal stage. After delivering the completion message and file paths, the workflow is done. If the user requests further revisions, loop back to `prompts/draft-and-review.md`. Otherwise, exit. diff --git a/samples/bmad-bmm-product-brief-preview/prompts/guided-elicitation.md b/samples/bmad-bmm-product-brief-preview/prompts/guided-elicitation.md deleted file mode 100644 index ec2e770..0000000 --- a/samples/bmad-bmm-product-brief-preview/prompts/guided-elicitation.md +++ /dev/null @@ -1,70 +0,0 @@ -**Language:** Use `{communication_language}` for all output. -**Output Language:** Use `{document_output_language}` for documents. - -# Stage 3: Guided Elicitation - -**Goal:** Fill the gaps in what you know. By now you have the user's brain dump, artifact analysis, and web research. This stage is about smart, targeted questioning — not rote section-by-section interrogation. - -**Skip this stage entirely in Yolo and Autonomous modes** — go directly to `prompts/draft-and-review.md`. - -## Approach - -You are NOT walking through a rigid questionnaire. You're having a conversation that covers the substance of a great product brief. The topics below are your mental checklist, not a script. Adapt to: -- What you already know (don't re-ask what's been covered) -- What the user is excited about (follow their energy) -- What's genuinely unclear (focus questions where they matter) - -## Topics to Cover (flexibly, conversationally) - -### Vision & Problem -- What core problem does this solve? For whom? -- How do people solve this today? What's frustrating about current approaches? -- What would success look like for the people this helps? -- What's the insight or angle that makes this approach different? - -### Users & Value -- Who experiences this problem most acutely? -- Are there different user types with different needs? -- What's the "aha moment" — when does a user realize this is what they needed? -- How does this fit into their existing workflow or life? - -### Market & Differentiation -- What competitive or alternative solutions exist? (Leverage web research findings) -- What's the unfair advantage or defensible moat? -- Why is now the right time for this? - -### Success & Scope -- How will you know this is working? What metrics matter? -- What's the minimum viable version that creates real value? -- What's explicitly NOT in scope for the first version? -- If this is wildly successful, what does it become in 2-3 years? - -## The Flow - -For each topic area where you have gaps: - -1. **Lead with what you know** — "Based on your input and my research, it sounds like [X]. Is that right?" -2. **Ask the gap question** — targeted, specific, not generic -3. **Reflect and confirm** — paraphrase what you heard -4. **"Anything else on this, or shall we move on?"** — the soft gate - -If the user is giving you detail beyond brief scope (requirements, architecture, platform details, timelines), **capture it silently** for the distillate. Acknowledge it briefly ("Good detail, I'll capture that") but don't derail the conversation. - -## When to Move On - -When you have enough substance to draft a compelling 1-2 page executive brief covering: -- Clear problem and who it affects -- Proposed solution and what makes it different -- Target users (at least primary) -- Some sense of success criteria or business objectives -- MVP-level scope thinking - -You don't need perfection — you need enough to draft well. Missing details can be surfaced during the review stage. - -If the user is providing complete, confident answers and you have solid coverage across all four topic areas after fewer than 3-4 exchanges, proactively offer to draft early. - -**Transition:** "I think I have a solid picture. Ready for me to draft the brief, or is there anything else you'd like to add?" - -## Stage Complete - -This stage is complete when sufficient substance exists to draft a compelling brief and the user confirms readiness. Route to `prompts/draft-and-review.md`. diff --git a/samples/bmad-bmm-product-brief-preview/resources/brief-template.md b/samples/bmad-bmm-product-brief-preview/resources/brief-template.md deleted file mode 100644 index 79c5a40..0000000 --- a/samples/bmad-bmm-product-brief-preview/resources/brief-template.md +++ /dev/null @@ -1,60 +0,0 @@ -# Product Brief Template - -This is a flexible guide for the executive product brief — adapt it to serve the product's story. Merge sections, add new ones, reorder as needed. The product determines the structure, not the template. - -## Sensible Default Structure - -```markdown -# Product Brief: {Product Name} - -## Executive Summary - -[2-3 paragraph narrative: What is this? What problem does it solve? Why does it matter? Why now? -This should be compelling enough to stand alone — if someone reads only this section, they should understand the vision.] - -## The Problem - -[What pain exists? Who feels it? How are they coping today? What's the cost of the status quo? -Be specific — real scenarios, real frustrations, real consequences.] - -## The Solution - -[What are we building? How does it solve the problem? -Focus on the experience and outcome, not the implementation.] - -## What Makes This Different - -[Key differentiators. Why this approach vs alternatives? What's the unfair advantage? -Be honest — if the moat is execution speed, say so. Don't fabricate technical moats.] - -## Who This Serves - -[Primary users — vivid but brief. Who are they, what do they need, what does success look like for them? -Secondary users if relevant.] - -## Success Criteria - -[How do we know this is working? What metrics matter? -Mix of user success signals and business objectives. Be measurable.] - -## Scope - -[What's in for the first version? What's explicitly out? -Keep this tight — it's a boundary document, not a feature list.] - -## Vision - -[Where does this go if it succeeds? What does it become in 2-3 years? -Inspiring but grounded.] -``` - -## Adaptation Guidelines - -- **For B2B products:** Consider adding a "Buyer vs User" section if they're different people -- **For platforms/marketplaces:** Consider a "Network Effects" or "Ecosystem" section -- **For technical products:** May need a brief "Technical Approach" section (keep it high-level) -- **For regulated industries:** Consider a "Compliance & Regulatory" section -- **If scope is well-defined:** Merge "Scope" and "Vision" into "Roadmap Thinking" -- **If the problem is well-known:** Shorten "The Problem" and expand "What Makes This Different" - -The brief should be 1-2 pages. If it's longer, you're putting in too much detail — that's what the distillate is for. diff --git a/samples/bmad-excalidraw/SKILL.md b/samples/bmad-excalidraw/SKILL.md index 33d0cb0..8ca1b18 100644 --- a/samples/bmad-excalidraw/SKILL.md +++ b/samples/bmad-excalidraw/SKILL.md @@ -42,19 +42,19 @@ Produce professional diagrams and visual aids as Excalidraw files through conver 3. **Detect diagram intent from user's request:** - What do they want to visualize? - - Did they specify a diagram type? If so, validate against `resources/diagram-types.md` + - Did they specify a diagram type? If so, validate against `references/diagram-types.md` - Did they specify enough detail to skip guided design? 4. **Route by mode:** - - Autonomous/YOLO → `prompts/diagram-generation.md` directly - - Guided → `prompts/guided-design.md` first, then `prompts/diagram-generation.md` + - Autonomous/YOLO → `diagram-generation.md` directly + - Guided → `guided-design.md` first, then `diagram-generation.md` ## Stages | # | Stage | Purpose | Prompt | |---|-------|---------|--------| -| 1 | Guided Design | Creative facilitation — brainstorm diagram type, content, layout | `prompts/guided-design.md` | -| 2 | Generation | Produce the `.excalidraw` file with proper layout | `prompts/diagram-generation.md` | +| 1 | Guided Design | Creative facilitation — brainstorm diagram type, content, layout | `guided-design.md` | +| 2 | Generation | Produce the `.excalidraw` file with proper layout | `diagram-generation.md` | Headless: skip guided-design, output file path on completion. diff --git a/samples/bmad-excalidraw/bmad-manifest.json b/samples/bmad-excalidraw/bmad-manifest.json index 3134061..f628727 100644 --- a/samples/bmad-excalidraw/bmad-manifest.json +++ b/samples/bmad-excalidraw/bmad-manifest.json @@ -5,14 +5,14 @@ "menu-code": "GD", "description": "Facilitates diagram design through conversational discovery.", "supports-headless": true, - "prompt": "prompts/guided-design.md" + "prompt": "guided-design.md" }, { "name": "diagram-generation", "menu-code": "DG", "description": "Generates Excalidraw diagram files from specifications.", "supports-headless": true, - "prompt": "prompts/diagram-generation.md" + "prompt": "diagram-generation.md" } ] } diff --git a/samples/bmad-excalidraw/prompts/diagram-generation.md b/samples/bmad-excalidraw/diagram-generation.md similarity index 97% rename from samples/bmad-excalidraw/prompts/diagram-generation.md rename to samples/bmad-excalidraw/diagram-generation.md index 4228555..79b3584 100644 --- a/samples/bmad-excalidraw/prompts/diagram-generation.md +++ b/samples/bmad-excalidraw/diagram-generation.md @@ -9,7 +9,7 @@ Generate a valid `.excalidraw` file from the diagram specification. Use the sche ## Step 1: Build the Diagram Specification -Create a JSON specification that the generation script can consume. Load `resources/excalidraw-schema.md` for the element format reference. +Create a JSON specification that the generation script can consume. Load `references/excalidraw-schema.md` for the element format reference. The specification format: diff --git a/samples/bmad-excalidraw/prompts/guided-design.md b/samples/bmad-excalidraw/guided-design.md similarity index 94% rename from samples/bmad-excalidraw/prompts/guided-design.md rename to samples/bmad-excalidraw/guided-design.md index 81122d0..7990c53 100644 --- a/samples/bmad-excalidraw/prompts/guided-design.md +++ b/samples/bmad-excalidraw/guided-design.md @@ -15,7 +15,7 @@ Capture any details they've already provided — don't re-ask what they've told ## Step 2: Suggest Diagram Type -Load `resources/diagram-types.md` for the full catalog. +Load `references/diagram-types.md` for the full catalog. Based on what you know, suggest the best-fit diagram type(s) with reasoning: @@ -77,4 +77,4 @@ Ask: "Ready to generate, or want to adjust anything?" ## Progression -When the user confirms → proceed to `prompts/diagram-generation.md` with the complete specification. +When the user confirms → proceed to `diagram-generation.md` with the complete specification. diff --git a/samples/bmad-excalidraw/resources/diagram-types.md b/samples/bmad-excalidraw/references/diagram-types.md similarity index 100% rename from samples/bmad-excalidraw/resources/diagram-types.md rename to samples/bmad-excalidraw/references/diagram-types.md diff --git a/samples/bmad-excalidraw/resources/excalidraw-schema.md b/samples/bmad-excalidraw/references/excalidraw-schema.md similarity index 100% rename from samples/bmad-excalidraw/resources/excalidraw-schema.md rename to samples/bmad-excalidraw/references/excalidraw-schema.md diff --git a/samples/planning-artifacts/bmad-distillation-generator-spec.md b/samples/planning-artifacts/bmad-distillation-generator-spec.md deleted file mode 100644 index c11e750..0000000 --- a/samples/planning-artifacts/bmad-distillation-generator-spec.md +++ /dev/null @@ -1,347 +0,0 @@ ---- -title: "Skill Spec: bmad-distillation-generator" -status: "complete" -created: "2026-03-13" -purpose: "Full specification for the skill builder agent to implement" -reference-skill: "bmad-bmm-product-brief-preview (use as architectural pattern)" ---- - -# bmad-distillation-generator — Skill Specification - -## Purpose - -A general-purpose utility skill that takes any set of input documents and produces a single hyper-compressed, token-efficient document (a "distillate") that an LLM can consume as sole context input for downstream workflows. The distillate is **lossless compression for an LLM reader** — every fact, decision, constraint, and relationship from the source documents is preserved, but all overhead that humans need and LLMs don't is stripped. - -This is a compression task, not a capture task. The skill assumes all relevant information has already been captured in the source documents. Its job is to produce the most token-efficient representation possible without losing signal. - -## What a Distillate Is - -A distillate is NOT a summary. Summaries are lossy — they capture the gist but drop detail. A distillate preserves all detail through lossless compression optimized for LLM consumption: - -- Every fact, decision, and constraint appears exactly once -- No prose transitions, rhetoric, or persuasion -- No repetition — deduplicated across all source documents -- No formatting for human scannability (decorative bold, whitespace for visual breathing room) -- No explaining things an LLM already knows (common terms, well-known companies, standard concepts) -- No hedging language ("we believe", "it's likely that") — state the signal directly -- Relationships between items are explicit, not implied -- Each item carries enough context to be understood without the source documents -- Rejected ideas and open questions are preserved — they prevent downstream re-proposal - -**Format:** Dense thematically-grouped bullets. Markdown structure for hierarchy only (## for themes, - for items). No decorative formatting. Every token carries signal. - -## Activation & Inputs - -### Required Inputs -- **source_documents** — One or more file paths or inline content to distill - -### Optional Inputs -- **downstream_consumer** — What workflow or agent will consume this distillate (e.g., "PRD creation", "architecture design", "story implementation"). When provided, the compressor uses this to judge what's signal vs noise. When omitted, preserve everything — no filtering. -- **token_budget** — Approximate target size. When provided and the distillate would exceed it, trigger semantic splitting. When omitted, produce the smallest possible single document. -- **output_path** — Where to save the distillate. When omitted, save adjacent to the primary source document with `-distillate.md` suffix. - -### Flags -- **--validate** — After producing the distillate, run a round-trip reconstruction test (see Validation section below) - -### Activation Modes -- **Direct invocation:** User calls the skill with inputs -- **Called by another skill:** Other BMAD skills (product brief, PRD, architecture) can invoke this as a final step after producing their primary document + discovery notes - -## Skill Architecture - -``` -bmad-distillation-generator/ - SKILL.md # Entry point, input validation, routing - agents/ - distillate-compressor.md # Core compression agent - round-trip-reconstructor.md # Validation: reconstructs source docs from distillate - prompts/ - compression-rules.md # The compression ruleset (shared reference) - splitting-strategy.md # Semantic splitting logic for large inputs - resources/ - distillate-format-reference.md # Format examples showing before/after -``` - -## Stages - -| # | Stage | Purpose | Location | -|---|-------|---------|----------| -| 1 | Validate & Analyze | Validate inputs, assess total size, detect document types | SKILL.md | -| 2 | Compress | Fan out compressor agent(s), produce distillate | agents/distillate-compressor.md | -| 3 | Verify & Output | Structured completeness check, save output | SKILL.md | -| 4 | Round-Trip Validation | (optional, --validate flag) Reconstruct sources from distillate, diff against originals | agents/round-trip-reconstructor.md | - -### Stage 1: Validate & Analyze (SKILL.md) - -1. **Validate inputs exist and are readable.** If source documents are paths, read them. If inline content, accept directly. - -2. **Assess total input size.** Count approximate tokens across all source documents. - -3. **Detect document types.** Understand what each source document is (product brief, discovery notes, research report, architecture doc, PRD, etc.) — this informs how to group themes in the output. - -4. **Determine splitting need.** If total input is large (heuristic: source documents collectively exceed ~15,000 tokens of content) AND no token_budget is set, warn the user that the distillate may be large and offer to split semantically. If token_budget is set and would require splitting, proceed automatically. - -5. **Route to Stage 2.** Pass all source content, downstream_consumer context, and splitting decision to the compressor. - -### Stage 2: Compress (agents/distillate-compressor.md) - -The compressor agent is the core of this skill. It receives all source document content and produces the distillate. - -**Compression process:** - -1. **Extract all discrete facts, decisions, constraints, requirements, relationships, rejected ideas, and open questions** from all source documents. Treat this as entity extraction — pull out every distinct piece of information. - -2. **Deduplicate ruthlessly.** If the same fact appears in the brief's executive summary AND the discovery notes' technical context, it appears once in the distillate. Choose the version with the most context. - -3. **Apply downstream filtering** (only if downstream_consumer is specified). For each extracted item, ask: "Would the downstream workflow need this?" Drop items that are clearly irrelevant to the stated consumer. When uncertain, keep. - -4. **Group thematically.** Organize items into coherent themes derived from the source content — not from a fixed template. The themes should reflect what the documents are actually about. Common groupings: core concept, problem/motivation, solution/approach, users/segments, technical decisions, constraints, scope boundaries, competitive context, rejected alternatives, open questions, risks. - -5. **Compress language.** For each item: - - Strip prose transitions and connective tissue - - Remove hedging and rhetoric - - Remove explanations of common knowledge - - Preserve specific details (numbers, names, versions, dates) - - Ensure the item is self-contained (understandable without reading the source) - - Make relationships explicit ("X because Y", "X blocks Y", "X replaces Y") - -6. **Apply the compression rules** from `prompts/compression-rules.md` as a final pass. - -**If semantic splitting is required:** - -7. **Identify natural semantic boundaries** in the source content. These are NOT arbitrary size breaks — they are coherent topic clusters that a downstream workflow might load independently. - -8. **Produce a root distillate** that contains: a 3-5 bullet orientation (what was distilled, for whom, how many parts), cross-references to section distillates, and any items that span multiple sections. - -9. **Produce section distillates**, each self-sufficient — a reader loading only one section should understand it without the others. Include a 1-line context header: "This section covers [topic]. Part N of M from [source document names]." - -### Stage 3: Verify & Output (SKILL.md) - -After the compressor returns: - -1. **Structured completeness check.** Extract all Level 2+ headings and key named entities (products, people, technologies, decisions) from the source documents. Verify each appears in the distillate. If gaps are found, send them back to the compressor for a targeted fix pass — not a full recompression. - -2. **Format check.** Verify the output follows distillate format rules: - - No prose paragraphs (only bullets) - - No decorative formatting - - No repeated information - - Each bullet is self-contained - - Themes are clearly delineated - -3. **Save output.** Write the distillate to the output path. Use frontmatter: - -```yaml ---- -type: bmad-distillate -sources: - - "{source file 1}" - - "{source file 2}" -downstream_consumer: "{consumer or 'general'}" -created: "{timestamp}" -token_estimate: {approximate token count} -parts: {1 or N if split} ---- -``` - -4. **Report to user or calling skill.** Return the file path(s) and a one-line confirmation. If called by another skill, return structured output: - -```json -{ - "status": "complete", - "distillate": "{path}", - "section_distillates": ["{path1}", "{path2}"] or null, - "token_estimate": N, - "source_documents": ["{path1}", "{path2}"], - "completeness_check": "pass" or "pass_with_additions" -} -``` - -## Compression Rules (for prompts/compression-rules.md) - -These rules govern how text is compressed. They are the core IP of this skill. - -### Strip — Remove entirely -- Prose transitions: "As mentioned earlier", "It's worth noting", "In addition to this" -- Rhetoric and persuasion: "This is a game-changer", "The exciting thing is" -- Hedging: "We believe", "It's likely that", "Perhaps", "It seems" -- Self-reference: "This document describes", "As outlined above" -- Common knowledge explanations: "Vercel is a cloud platform company", "MIT is an open-source license" -- Repeated introductions of the same concept -- Section transition paragraphs -- Formatting-only elements (decorative bold/italic for emphasis, horizontal rules for visual breaks) - -### Preserve — Keep always -- Specific numbers, dates, versions, percentages -- Named entities (products, companies, people, technologies) -- Decisions made and their rationale (compressed: "Decision: X. Reason: Y") -- Rejected alternatives and why (compressed: "Rejected: X. Reason: Y") -- Explicit constraints and non-negotiables -- Dependencies and ordering relationships -- Open questions and unresolved items -- Scope boundaries (in/out/deferred) -- Success criteria and how they're validated -- User segments and what success means for each - -### Transform — Change form for efficiency -- Long prose paragraphs → single dense bullet capturing the same information -- "We decided to use X because Y and Z" → "X (rationale: Y, Z)" -- Repeated category labels → group under a single heading, no per-item labels -- "Risk: ... Severity: high" → "HIGH RISK: ..." -- Conditional statements → "If X → Y" form -- Multi-sentence explanations → semicolon-separated compressed form - -### Deduplication Rules -- Same fact in multiple documents → keep the version with most context -- Same concept at different detail levels → keep the detailed version -- Overlapping lists → merge into single list, no duplicates -- When source documents disagree → note the conflict explicitly: "Brief says X; discovery notes say Y — unresolved" - -## Format Reference (for resources/distillate-format-reference.md) - -### Before (human-readable brief excerpt) -``` -## What Makes This Different - -**The anti-fragmentation layer.** The AI tooling space is fracturing across 40+ -platforms with no shared methodology layer. BMAD is uniquely positioned to be the -cross-platform constant — the structured approach that works the same in Cursor, -Claude Code, Windsurf, Copilot, and whatever launches next month. Every other -methodology or skill framework maintains its own platform support matrix. By -building on the open-source skills CLI ecosystem, BMAD offloads the highest-churn -maintenance burden and focuses on what actually differentiates it: the methodology -itself. -``` - -### After (distillate) -``` -## Differentiation -- Anti-fragmentation positioning: BMAD = cross-platform constant across 40+ fragmenting AI tools; no competitor provides shared methodology layer -- Platform complexity delegated to Vercel skills CLI ecosystem (MIT); BMAD maintains methodology, not platform configs -``` - -### Before (discovery notes excerpt) -``` -## Competitive Landscape - -- **Vercel Skills.sh**: 83K+ skills, 18 agents, largest curated leaderboard — - but dev-only, skills trigger unreliably (20% without explicit prompting) -- **SkillsMP**: 400K+ skills directory, pure aggregator with no curation or CLI -- **ClawHub/OpenClaw**: ~3.2K curated skills with versioning/rollback, small ecosystem -- **Lindy**: No-code AI agent builder for business automation — closed platform, - no skill sharing -- **Microsoft Copilot Studio**: Enterprise no-code agent builder — vendor-locked - to Microsoft -- **MindStudio**: No-code AI agent platform — siloed, no interoperability -- **Make/Zapier AI**: Workflow automation adding AI agents — workflow-centric, - not methodology-centric -- **Key gap**: NO competitor combines structured methodology with plugin - marketplace — this is BMAD's whitespace -``` - -### After (distillate) -``` -## Competitive Landscape -- No competitor combines structured methodology + plugin marketplace (whitespace) -- Skills.sh (Vercel): 83K skills, 18 agents, dev-only, 20% trigger reliability -- SkillsMP: 400K skills, aggregator only, no curation/CLI -- ClawHub: 3.2K curated, versioning, small ecosystem -- No-code platforms (Lindy, Copilot Studio, MindStudio, Make/Zapier): closed/siloed, no skill portability, business-only -``` - -## Stage 4: Round-Trip Validation (agents/round-trip-reconstructor.md) - -**Triggered by:** `--validate` flag. Optional. Not run by default. - -**Purpose:** Prove the distillate is lossless by reconstructing the original source documents from the distillate alone, then diffing against the originals to surface any information loss. - -### Process - -1. **The reconstructor agent receives ONLY the distillate.** It has no access to the original source documents. This is critical — if it could see the originals, the test is meaningless. - -2. **Detect source document types from the distillate's frontmatter.** The `sources` field lists what was distilled. The reconstructor uses the document type (product brief, discovery notes, architecture doc, etc.) to understand what kind of document to reconstruct. - -3. **Reconstruct each source document.** For each source listed in frontmatter, produce a full human-readable document from the distillate's content alone. The reconstruction should: - - Use appropriate prose, structure, and formatting for the document type - - Include all sections the original would have had - - Not invent information — only use what's in the distillate - - Flag any places where the distillate felt insufficient with `[POSSIBLE GAP]` markers - -4. **Save reconstructions** as temporary files adjacent to the distillate with `-reconstruction-{N}.md` suffixes. - -### Diff Analysis (back in SKILL.md) - -After the reconstructor returns, the main skill performs the diff: - -1. **Read both the original source documents and the reconstructions.** - -2. **Semantic diff, not text diff.** Don't compare prose word-for-word — compare information content. For each section of the original, ask: - - Is the core information present in the reconstruction? - - Are specific details preserved (numbers, names, decisions)? - - Are relationships and rationale intact? - - Did the reconstruction add anything not in the original? (indicates hallucination to fill gaps) - -3. **Produce a validation report** saved adjacent to the distillate as `-validation-report.md`: - -```markdown ---- -type: distillate-validation -distillate: "{distillate path}" -sources: ["{source paths}"] -created: "{timestamp}" ---- - -## Validation Summary -- Status: PASS | PASS_WITH_WARNINGS | FAIL -- Information preserved: {percentage estimate} -- Gaps found: {count} -- Hallucinations detected: {count} - -## Gaps (information in originals but missing from reconstruction) -- {gap description} — Source: {which original}, Section: {where} - -## Hallucinations (information in reconstruction not traceable to originals) -- {hallucination description} — appears to fill gap in: {section} - -## Possible Gap Markers (flagged by reconstructor) -- {marker description} -``` - -4. **If gaps are found**, offer to run a targeted fix pass on the distillate — adding the missing information without full recompression. - -5. **Clean up** — delete the temporary reconstruction files after the report is generated (the report preserves the findings). - -### When to use --validate - -- During development/testing of the distillation generator itself -- When distilling critical documents where information loss is unacceptable (architecture decisions, compliance-relevant specs) -- As a quality gate before handing off a distillate to a high-stakes downstream workflow -- NOT for routine use — it adds significant token cost (full reconstruction + diff analysis) - -## Design Rationale - -### Why a separate skill, not inline in each workflow? -Compression is a distinct competency. The agent producing a brief is optimized for collaborative discovery and persuasive writing. The agent producing a distillate is optimized for ruthless information extraction and deduplication. Separating them means each can be excellent at its job. It also means any BMAD workflow can call the same distillation skill — briefs, PRDs, architecture docs, research reports — without each reimplementing compression logic. - -### Why self-check instead of a separate validator? -The completeness check is mechanical (does each heading/entity from source appear in output?) not judgmental. A checklist-based self-audit is reliable for this task. A separate validator agent adds a round-trip and token cost for marginal benefit. If the downstream workflow finds gaps, it can always read the source documents directly — the distillate is an optimization, not a single point of failure. A validator can be added later if needed. - -### Why round-trip reconstruction for validation? -The strongest proof of lossless compression is reconstruction. If an LLM reading only the distillate can reproduce both source documents with no meaningful information loss, the distillate is complete. The delta between originals and reconstructions is a precise quality metric: missing information = compression loss, added information = hallucination filling gaps (which also flags where the distillate was too terse). This is more rigorous than any checklist-based approach because it tests actual recoverability, not just presence of keywords. - -### Why semantic splitting instead of size-based? -Arbitrary splits (every N tokens) break coherence. A downstream workflow loading "part 2 of 4" of a size-split distillate gets context fragments. Semantic splits produce self-contained topic clusters that a workflow can load selectively — "give me just the technical decisions section" — which is more useful and more token-efficient for the consumer. - -## Integration Points - -### As a standalone skill -User invokes directly: "distill these documents for PRD creation" or "create a distillate of the architecture doc" - -### Called by other BMAD skills -Any skill that produces a primary document + discovery notes can call this as a final optional step: -- Product Brief → offers distillate for PRD creation -- PRD → offers distillate for architecture/story creation -- Architecture → offers distillate for implementation stories -- Research Reports → offers distillate for brief/PRD input - -### Calling convention for other skills -Other skills invoke this by telling the LLM to run the `bmad-distillation-generator` skill with the source documents and downstream consumer specified. The distillation skill handles everything else and returns the output path. diff --git a/samples/planning-artifacts/product-brief-bmad-next-gen-installer-discovery-notes.md b/samples/planning-artifacts/product-brief-bmad-next-gen-installer-discovery-notes.md deleted file mode 100644 index 87d92a9..0000000 --- a/samples/planning-artifacts/product-brief-bmad-next-gen-installer-discovery-notes.md +++ /dev/null @@ -1,120 +0,0 @@ ---- -title: "Discovery Notes: BMAD Next-Gen Installer" -type: discovery-notes -source: "product-brief-bmad-next-gen-installer.md" -created: "2026-03-12" -purpose: "Detailed supporting context captured during product brief discovery" ---- - -## Current Installer Architecture (Migration Context) - -- Entry point: `tools/cli/bmad-cli.js` using Commander.js, routes install/uninstall/status commands -- Core installer: `tools/cli/installers/lib/core/installer.js` orchestrates all installation -- Platform configs: `tools/cli/installers/lib/ide/platform-codes.yaml` defines ~20 platforms with target dirs, legacy dirs, template types, and special flags (ancestor conflict checks, skill format toggles) -- Manifest generation: produces CSV files (`skill-manifest.csv`, `workflow-manifest.csv`, `agent-manifest.csv`) — these are the current source of truth, NOT the JSON manifests -- External modules: `tools/cli/commands/external-official-modules.yaml` lists official modules (CIS, GDS, TEA, WDS) installed from npm with semver -- Dependency resolution: 4-pass system (collect primary files, parse deps, resolve paths, resolve transitive) — limited to YAML-declared deps -- Config collection: prompts user for name, communication language, document output language, output folder path -- Current install directory structure: `_bmad/` for core files, `._config/` for manifests, plus per-IDE skill directories (`.claude/skills/`, `.cursor/skills/`, etc.) -- Supports install, update, quick-update, and compile-agents actions -- Custom modules supported via file paths in addition to npm packages - -## Existing Skill/Manifest Primitives (Already Partially Built) - -- Skills already use directory-per-skill layout: `skill-name/SKILL.md` with frontmatter (name, description) -- `bmad-manifest.json` sidecar files already exist alongside skills — example from product-brief skill: `{"module-code": "bmm", "replaces-skill": "bmad-create-product-brief", "capabilities": [{"name": "create-brief", "menu-code": "CB", "description": "...", "supports-headless": true, "phase-name": "1-analysis", "after": ["brainstorming"], "before": ["create-prd"], "is-required": true, "output-location": "{planning_artifacts}"}]}` -- `bmad-skill-manifest.yaml` files define `canonicalId` and artifact type in source -- The gap: JSON manifests exist but CSV remains single source of truth; no runtime scanning/registration; manifests are static, generated once at install - -## Vercel Skills CLI Technical Details - -- CLI tool: `npx skills add ` — installs from GitHub repos, GitLab, local paths, git URLs -- Supports 40+ agents with per-agent path mappings (Claude Code: `.claude/skills/`, Cursor: `.cursor/skills/`, etc.) -- Installation methods: symlinks (recommended) or copies -- Scope: project-level (shared via git) or global (user-wide) -- Discovery: scans `skills/`, `.agents/skills/`, agent-specific paths, and `.claude-plugin/marketplace.json` manifests -- Recognizes Anthropic plugin marketplace format: `{"metadata": {"pluginRoot": "./plugins"}, "plugins": [{"name": "my-plugin", "skills": ["./skills/review"]}]}` -- Key commands: add, list, find, remove, check, update, init -- Supports interactive selection or non-interactive CI/CD flags (`-y`, `--all`) -- MIT licensed, backed by Vercel - -## Competitive Landscape - -- **Vercel Skills.sh**: 83K+ skills, 18 agents, largest curated leaderboard — but dev-only, skills trigger unreliably (20% without explicit prompting) -- **SkillsMP**: 400K+ skills directory, pure aggregator with no curation or CLI -- **ClawHub/OpenClaw**: ~3.2K curated skills with versioning/rollback, small ecosystem -- **Lindy**: No-code AI agent builder for business automation — closed platform, no skill sharing -- **Microsoft Copilot Studio**: Enterprise no-code agent builder — vendor-locked to Microsoft -- **MindStudio**: No-code AI agent platform — siloed, no interoperability -- **Make/Zapier AI**: Workflow automation adding AI agents — workflow-centric, not methodology-centric -- **Key gap**: NO competitor combines structured methodology with plugin marketplace — this is BMAD's whitespace - -## Market Context - -- AI agent market: $7.84B in 2025, projected $52.62B by 2030 -- Agent Skills spec is ~4 months old, ecosystem grew from thousands to 351K+ skills in that time -- Three standards converging under Linux Foundation's AAIF: MCP (tool integration, 97M monthly SDK downloads), AGENTS.md (project instructions), A2A (agent-to-agent communication) -- Skills quality crisis: 13.4% have critical vulnerabilities (Snyk study); most community skills are "AI slop" -- Skill activation reliability is a known problem: 20% trigger rate without explicit prompting — BMAD's structured invocation patterns may be an advantage here -- BMAD already has established presence: GitHub repo, npm package, docs site, organic coverage on DEV.to and Medium - -## User & Distribution Requirements Captured - -- NPX installer should still exist for technical users, potentially wrapping Vercel skills CLI -- Non-technical path: download zip, get platform-specific README, copy skills to folder, run bmad-init -- No requirement for Node.js, Git, or terminal for the non-technical path -- Install messages (like current installer shows) are valued — NPX path should preserve this UX -- Users may share bundles peer-to-peer, not just from marketplace -- Marketplace initially just a download button + zip + README popup with instructions -- As low-code platforms mature, provide better per-platform guidance — but this is an emerging space, we're betting on the future - -## Technical Decisions & Constraints - -- Adopt Anthropic plugin standard as base format (what Vercel uses) -- `bmad-manifest.json` extends the base standard for BMAD-specific needs (installer options, capabilities, help system integration, phase ordering, dependency declarations) -- bmad-init must always be included as a base skill in every bundle/install (solves bootstrapping problem) -- Vercel CLI integration pattern (wrap vs fork vs call) is a PRD/architecture decision -- Manifest format stability is critical once third-party authors publish against it — needs careful upfront design -- Migration from current CSV-based manifests to JSON-based runtime scanning is a key technical shift - -## Quality & Curation Model - -- All plugin submissions will be gated — not an open bazaar -- Human review by BMad and core team personally -- This is a key differentiator: curated quality vs ecosystem noise -- Certification process details are out of scope for the brief, but gated-submission is a core architectural requirement -- The quality gate becomes MORE valuable over time as the broader ecosystem gets noisier - -## Scope Signals (In/Out/Maybe for PRD) - -- **In**: manifest spec, bmad-init, bmad-update, Vercel CLI integration, NPX installer, zip bundles, migration path -- **Out**: BMAD Builder, marketplace web platform, skill conversion work, one-click install for all platforms, monetization -- **Maybe/Future**: deeper platform-specific integrations for non-technical users, CI/CD integration (bmad-init as GitHub Action one-liner), telemetry/usage analytics for module authors, offline/air-gapped enterprise install story, integrity verification for zip bundles (checksums/signing) - -## Rejected Ideas / Decisions Made - -- **Not building our own platform support matrix going forward** — delegating to Vercel skills CLI ecosystem. Rationale: maintaining 20+ platform configs is the biggest maintenance burden; it's unsustainable at 40+ -- **Not requiring one-click install for non-technical users in v1** — emerging space, guidance-based for now. Rationale: we don't know what all the low-code platforms will be; better to provide good READMEs and improve over time -- **Not using existing roadmap or prior brainstorming** — starting fresh for this initiative. Rationale: BMad wanted a clean vision unconstrained by previous planning - -## Open Questions for PRD - -- Exact Vercel skills CLI integration pattern: wrap as subprocess? Fork and bundle? Use as a library? Peer dependency? -- How does bmad-update work technically? Diff-based? Full replacement? Does it preserve user customizations? -- What's the migration story for existing users? Migration command? Manual reinstall? Compatibility shim? -- How do we test installation correctness across 40+ platforms? CI matrix for top N? Community testing? -- Should bmad-manifest.json be proposed as an open standard to Agent Skills governance? -- How do we handle platforms NOT supported by the Vercel skills CLI? -- What's the manifest versioning strategy? How do we evolve the format without breaking existing plugins? -- What does the plugin author getting-started experience look like? What tooling do they need? - -## Reviewer Insights Worth Preserving - -- **Opportunity**: Module authors are an acquisition channel — every published plugin is a distribution event bringing the creator's audience into the ecosystem -- **Opportunity**: CI/CD integration (bmad-init as a pipeline one-liner) makes BMAD part of repo infrastructure, dramatically increasing stickiness -- **Opportunity**: Educational institutions are an overlooked segment — structured methodology + non-technical install maps onto university AI curriculum -- **Opportunity**: Skill composability as a first-class primitive — letting users mix BMAD modules with third-party skills for custom methodology stacks -- **Risk**: Manifest format evolution creates a versioning/compatibility matrix — once third-party authors publish, changes break plugins (same maintenance burden in a new form) -- **Risk**: "Methodology-backed quality" needs to be a defined process, not just a claim — the gated review model addresses this -- **Risk**: Platform proliferation means 40+ testing environments, even with Vercel handling translation -- **Risk**: Scope creep pressure from marketplace vision — brief explicitly excludes it but it's the primary long-term value diff --git a/samples/planning-artifacts/product-brief-bmad-next-gen-installer-distillate.md b/samples/planning-artifacts/product-brief-bmad-next-gen-installer-distillate.md deleted file mode 100644 index 2f01674..0000000 --- a/samples/planning-artifacts/product-brief-bmad-next-gen-installer-distillate.md +++ /dev/null @@ -1,109 +0,0 @@ ---- -type: bmad-distillate -sources: - - "product-brief-bmad-next-gen-installer.md" - - "product-brief-bmad-next-gen-installer-discovery-notes.md" -downstream_consumer: "PRD creation" -created: "2026-03-13" ---- - -## Core Concept -- BMAD Next-Gen Installer: replaces monolithic Node.js CLI with skill-based plugin architecture for distributing BMAD methodology across 40+ AI platforms -- Three layers: self-describing plugins (bmad-manifest.json), cross-platform install via Vercel skills CLI (MIT), runtime registration via bmad-init skill -- Transforms BMAD from dev-only methodology into open platform for any domain (creative, therapeutic, educational, personal) - -## Problem -- Current installer maintains ~20 platform configs manually; each platform convention change requires installer update, test, release — largest maintenance burden on team -- Node.js/npm required — blocks non-technical users on UI-based platforms (Claude Co-Work, etc.) -- CSV manifests are static, generated once at install; no runtime scanning/registration -- Unsustainable at 40+ platforms; new tools launching weekly - -## Solution Architecture -- Plugins: skill bundles with Anthropic plugin standard as base format + bmad-manifest.json extending for BMAD-specific metadata (installer options, capabilities, help integration, phase ordering, dependencies) -- Existing manifest example: `{"module-code":"bmm","replaces-skill":"bmad-create-product-brief","capabilities":[{"name":"create-brief","menu-code":"CB","supports-headless":true,"phase-name":"1-analysis","after":["brainstorming"],"before":["create-prd"],"is-required":true}]}` -- Vercel skills CLI handles platform translation; integration pattern (wrap/fork/call) is PRD decision -- bmad-init: global skill scanning installed bmad-manifest.json files, registering capabilities, configuring project settings; always included as base skill in every bundle (solves bootstrapping) -- bmad-update: plugin update path without full reinstall; technical approach (diff/replace/preserve customizations) is PRD decision -- Distribution tiers: (1) NPX installer wrapping skills CLI for technical users, (2) zip bundle + platform-specific README for non-technical users, (3) future marketplace -- Non-technical path has honest friction: "copy to right folder" requires knowing where that folder is; per-platform README instructions for common tools; improves over time as low-code space matures - -## Differentiation -- Anti-fragmentation: BMAD = cross-platform constant; no competitor provides shared methodology layer across AI tools -- Curated quality: all submissions gated, human-reviewed by BMad + core team personally; 13.4% of community skills have critical vulnerabilities (Snyk 2026); quality gate value increases as ecosystem gets noisier -- Domain-agnostic: no competitor builds beyond software dev workflows; same plugin system powers any domain via BMAD Builder (separate initiative) - -## Users (ordered by v1 priority) -- Module authors (primary v1): package/test/distribute plugins independently without installer changes -- Developers: single-command install on any of 40+ platforms via NPX -- Non-technical users: install without Node/Git/terminal; emerging segment including PMs, designers, educators -- Future plugin creators: non-dev authors using BMAD Builder; need distribution without building own installer - -## Success Criteria -- Zero (or near-zero) custom platform directory code; delegated to skills CLI ecosystem -- Installation verified on top platforms by volume; skills CLI handles long tail -- Non-technical install path validated with non-developer users -- bmad-init discovers/registers all plugins from manifests; clear errors for malformed manifests -- At least one external module author successfully publishes plugin using manifest system -- bmad-update works without full reinstall -- Existing CLI users have documented migration path - -## Scope -- In: manifest spec, bmad-init, bmad-update, Vercel CLI integration, NPX installer, zip bundles, migration path -- Out: BMAD Builder, marketplace web platform, skill conversion (prerequisite, separate), one-click install for all platforms, monetization, quality certification process (gated-submission principle is architectural requirement; process defined separately) -- Deferred: CI/CD integration, telemetry for module authors, air-gapped enterprise install, zip bundle integrity verification (checksums/signing), deeper non-technical platform integrations - -## Current Installer (migration context) -- Entry: `tools/cli/bmad-cli.js` (Commander.js) → `tools/cli/installers/lib/core/installer.js` -- Platforms: `tools/cli/installers/lib/ide/platform-codes.yaml` (~20 platforms with target dirs, legacy dirs, template types, special flags) -- Manifests: CSV files (skill/workflow/agent-manifest.csv) are current source of truth, not JSON -- External modules: `external-official-modules.yaml` (CIS, GDS, TEA, WDS) from npm with semver -- Dependencies: 4-pass resolver (collect → parse → resolve → transitive); YAML-declared only -- Config: prompts for name, communication language, document output language, output folder -- Actions: install, update, quick-update, compile-agents -- Skills already use directory-per-skill layout (skill-name/SKILL.md); bmad-manifest.json sidecars already exist but are not source of truth -- Key shift: CSV-based static manifests → JSON-based runtime scanning - -## Vercel Skills CLI -- `npx skills add ` — GitHub, GitLab, local paths, git URLs -- 40+ agents; per-agent path mappings; symlinks (recommended) or copies -- Scopes: project-level or global -- Discovery: `skills/`, `.agents/skills/`, agent-specific paths, `.claude-plugin/marketplace.json` -- Commands: add, list, find, remove, check, update, init -- Non-interactive: `-y`, `--all` flags for CI/CD - -## Competitive Landscape -- No competitor combines structured methodology + plugin marketplace (whitespace) -- Skills.sh (Vercel): 83K skills, dev-only, 20% trigger reliability without explicit prompting -- SkillsMP: 400K skills, aggregator only, no curation -- ClawHub: 3.2K curated, versioning, small -- No-code platforms (Lindy, Copilot Studio, MindStudio, Make/Zapier): closed/siloed, no skill portability, business-only -- Market: $7.84B (2025) → $52.62B (2030); Agent Skills spec ~4 months old, 351K+ skills; standards converging under Linux Foundation AAIF (MCP, AGENTS.md, A2A) -- BMAD's structured invocation patterns may advantage vs 20% trigger reliability problem - -## Rejected Alternatives -- Building own platform support matrix: unsustainable at 40+; delegate to Vercel ecosystem -- One-click install for non-technical v1: emerging space; guidance-based, improve over time -- Prior roadmap/brainstorming: clean start, unconstrained by previous planning - -## Open Questions -- Vercel CLI integration pattern: wrap/fork/call/peer dependency? -- bmad-update mechanics: diff/replace? Preserve user customizations? -- Migration story: command/manual reinstall/compatibility shim? -- Cross-platform testing: CI matrix for top N? Community testing for rest? -- bmad-manifest.json as open standard submission to Agent Skills governance? -- Platforms NOT supported by Vercel skills CLI? -- Manifest versioning strategy for backward compatibility? -- Plugin author getting-started experience and tooling? - -## Opportunities (from review) -- Module authors as acquisition channel: each published plugin distributes BMAD to creator's audience -- CI/CD integration: bmad-init as pipeline one-liner increases stickiness -- Educational institutions: structured methodology + non-technical install → university AI curriculum -- Skill composability: mixing BMAD modules with third-party skills for custom methodology stacks - -## Risks -- Manifest format evolution creates versioning/compatibility burden once third-party authors publish -- Quality gate needs defined process, not just claim — gated review model addresses -- 40+ platform testing environments even with Vercel handling translation -- Scope creep pressure from marketplace vision (explicitly excluded but primary long-term value) -- Vercel dependency: minor supply-chain risk; MIT license allows fork if deprioritized; supporting many platforms is core differentiator regardless diff --git a/samples/planning-artifacts/product-brief-bmad-next-gen-installer.md b/samples/planning-artifacts/product-brief-bmad-next-gen-installer.md deleted file mode 100644 index cca4f7c..0000000 --- a/samples/planning-artifacts/product-brief-bmad-next-gen-installer.md +++ /dev/null @@ -1,96 +0,0 @@ ---- -title: "Product Brief: BMAD Next-Gen Installer" -status: "complete" -created: "2026-03-12" -updated: "2026-03-12" -inputs: - - "User brain dump (BMad)" - - "Current installer codebase analysis (tools/cli/)" - - "Vercel skills CLI README (github.com/vercel-labs/skills)" - - "Web research: AI agent skills ecosystem, marketplace landscape" ---- - -# Product Brief: BMAD Next-Gen Installer - -## Executive Summary - -The BMAD Method has grown from a developer-focused agile AI methodology into a framework used across 20+ platforms — but its installer hasn't kept up. Today, every new AI tool that supports skills means manual work: adding platform configs, maintaining directory mappings, testing installation paths. This doesn't scale, and it locks BMAD out of the fastest-growing segment of the market: non-technical users on low-code and UI-based platforms. - -The Next-Gen Installer replaces BMAD's monolithic Node.js CLI with a skill-based architecture built on the emerging Agent Skills standard. By leveraging the open-source Vercel skills CLI for cross-platform installation and introducing a plugin system where BMAD modules are self-describing skill bundles, we eliminate the platform maintenance burden, open distribution beyond what BMAD could maintain alone, and lay the foundation for a marketplace where anyone — developers, creators, educators, therapists — can discover, download, and install BMAD plugins without needing Git, Node, or a terminal. - -This isn't just a better installer. It's the infrastructure that transforms BMAD from a dev methodology into an open platform. - -## The Problem - -BMAD currently supports ~20 AI platforms through a custom Node.js installer that maintains per-platform directory mappings, template formats, and legacy migration paths. Every platform that changes its skill conventions — and they change constantly — requires installer updates, testing, and a new release. This is the single biggest maintenance burden on the bmad-code team. - -Meanwhile, the Agent Skills ecosystem has exploded. The broader skills ecosystem now spans 40+ platforms with hundreds of thousands of skills and millions of installs. The market is moving fast, and BMAD is fighting to keep up with platform-by-platform manual support while new tools launch weekly. - -Worse, the current installer requires Node.js and npm — a hard barrier for the growing population of non-technical users building with AI through UI-based platforms like Claude Co-Work. These users can't run `npx bmad-method install`. They need something simpler. - -The cost of the status quo is clear: developer time spent maintaining platform configs instead of building methodology, and an entire user segment that can't access BMAD at all. - -## The Solution - -The Next-Gen Installer is a skill-based distribution and registration system with three layers: - -**1. Self-Describing Plugins.** Every BMAD module becomes a plugin — a bundle of skills with a manifest that declares what's included, how skills relate to each other, what capabilities they provide, and how they integrate with the BMAD help system. The plugin format adopts the Anthropic plugin standard (used by Vercel and the broader skills ecosystem) as its base, extended with a BMAD-specific manifest (`bmad-manifest.json`) for metadata the base standard doesn't cover — such as installer options, capability declarations, and help system integration. A plugin is fully self-contained: download it, put the skills in your tool's skill folder, and it works. - -**2. Cross-Platform Installation via Vercel Skills CLI.** For users who want an automated install experience, the installer builds on the MIT-licensed Vercel skills CLI, which handles translating the Anthropic plugin standard to 40+ platforms. The exact integration pattern — wrapping, forking, or calling as a dependency — is a PRD-level architecture decision. The strategic intent is clear: BMAD stops maintaining platform directory mappings and delegates that problem to a well-maintained open-source project. The Vercel dependency carries minor supply-chain risk, but the pros far outweigh it: the MIT license means BMAD can fork and maintain it if Vercel ever deprioritizes the project. Supporting many platforms is a core BMAD differentiator — we need this problem solved one way or another, and leveraging an existing solution beats building from scratch. - -**3. Runtime Registration via `bmad-init`.** A global skill that scans for installed BMAD manifests, registers capabilities, configures project settings, and bootstraps the BMAD experience. Users run it once after installation. It replaces the current installer's config-collection step and provides the entry point for updates via `bmad-update`. Note: `bmad-init` itself must be installed before it can run — the NPX installer and zip bundle README handle this bootstrapping step by ensuring `bmad-init` is always included as a base skill. - -For non-technical users, distribution is straightforward: download a zip containing all plugin skills plus a README with platform-specific guidance. The honest reality is that "copy to the right folder" still requires knowing where that folder is — and this varies by platform. The README provides per-platform instructions for the most common tools, and as the low-code/no-code AI platform space matures, we improve guidance and explore deeper integrations. We don't need to solve universal one-click install today, but we do need to be honest that the non-technical path has friction we'll reduce over time. - -## What Makes This Different - -**The anti-fragmentation layer.** The AI tooling space is fracturing across 40+ platforms with no shared methodology layer. BMAD is uniquely positioned to be the cross-platform constant — the structured approach that works the same in Cursor, Claude Code, Windsurf, Copilot, and whatever launches next month. Every other methodology or skill framework maintains its own platform support matrix. By building on the open-source skills CLI ecosystem, BMAD offloads the highest-churn maintenance burden and focuses on what actually differentiates it: the methodology itself. - -**Methodology-backed quality in a sea of AI slop.** The broader skills ecosystem is flooded with low-quality, AI-generated content — and early research (Snyk, 2026) suggests a meaningful percentage of community skills contain security vulnerabilities. BMAD plugins are different: they're structured, tested, and part of a coherent methodology. The BMAD manifest system ensures skills work together, declare dependencies, and integrate with the help system. This is a curated ecosystem, not an open bazaar — all plugin submissions will be gated, reviewed, and curated by the BMAD creator and open-source core team. This human-reviewed quality gate is a key differentiator that becomes more valuable as the broader ecosystem grows noisier. - -**Platform for everything, not just code.** No competitor in the AI skills space is building beyond software development workflows. BMAD's plugin architecture is domain-agnostic — the same manifest system, installer, and registration flow that powers the dev methodology will power creative, educational, therapeutic, and personal plugins built with the BMAD Builder. This is unaddressed whitespace in the current market. - -## Who This Serves - -**BMAD Open-Source Contributors and Module Authors** (primary v1 target) — The people who build BMAD modules today. They currently package workflows and agents manually and rely on the installer team to support new platforms. They need a standardized way to package modules as self-contained skill plugins that work anywhere — and they need to do it without waiting on installer changes. Success: a module author can package, test, and distribute a plugin independently. - -**Developers Using AI Coding Tools** — Technical users across Claude Code, Cursor, Gemini CLI, Codex, and dozens of other platforms who want to install BMAD with a single command and have it just work, regardless of their tool. Success: `npx` one-liner installs BMAD to their tool of choice, and `bmad-init` configures it for their project. - -**Non-Technical AI Users** — People building with AI through UI-based platforms who don't have (or want) a development environment. They need download-and-copy simplicity with clear, platform-specific guidance. This is an emerging segment — we don't fully understand their needs yet, but removing the Node.js barrier opens BMAD to product managers, designers, educators, and knowledge workers who currently cannot access it. Success: a user who has never opened a terminal can install and use BMAD on their platform. - -**Future Plugin Creators** — People who will build BMAD-compatible plugins for domains beyond software development. They need a distribution system that gets their work into users' hands without building their own installer. Success: a non-dev plugin author can package and share their creation using the same manifest and distribution system. - -## Success Criteria - -- **Platform maintenance burden reduced dramatically:** Custom platform directory code in BMAD's codebase approaches zero, with cross-platform installation delegated to the skills CLI ecosystem -- **Broad platform coverage:** Installation verified on the top platforms by install volume, with the skills CLI handling the long tail -- **Non-technical installation path exists:** Users can install BMAD without Node.js, npm, or Git — validated by at least testing the flow with non-developer users -- **Plugin self-registration works:** `bmad-init` correctly discovers and registers all installed BMAD plugins from manifests alone, with clear error messages for malformed or missing manifests -- **Module authors can package and distribute plugins** using the manifest system without needing installer changes — validated by at least one external module author successfully publishing a plugin -- **Update path exists:** `bmad-update` allows users to update installed plugins without reinstalling from scratch -- **Migration from current installer:** Existing BMAD users on the Node.js CLI have a clear, documented path to the next-gen system - -## Scope - -**In scope for the next-gen installer:** -- Plugin manifest format (`bmad-manifest.json`) and specification -- `bmad-init` skill for runtime discovery and registration -- `bmad-update` skill for plugin updates -- Integration with Vercel skills CLI (or equivalent) for automated cross-platform installation -- NPX-based installer for technical users -- Downloadable zip bundles with platform-specific README guidance for non-technical users -- Migration path from current installer — existing users need a clear upgrade story, whether that's a migration command or documented manual steps - -**Explicitly out of scope:** -- BMAD Builder (plugin creation tool) — separate initiative -- Marketplace platform (web-based discovery and download) — future phase -- Converting existing workflows/agents to skills — prerequisite, handled separately -- One-click install for every platform — emerging space, guidance-based for now -- Monetization or paid plugin infrastructure -- Plugin quality certification process — the review and curation workflow will be defined separately, though the gated-submission principle is a core architectural requirement - -## Vision - -If the next-gen installer succeeds, BMAD becomes the first AI agent methodology that is truly platform-agnostic and accessible to non-developers. The plugin architecture creates the foundation for a marketplace where a therapist can download a "Guided Journaling" BMAD plugin, a game designer can install a "World Building" plugin, and a startup founder can get the full software development methodology — all through the same system, on whatever AI platform they use. - -In 2-3 years, BMAD plugins become a leading way people package and share structured AI agent workflows. The combination of methodology-backed quality, cross-platform portability, and open distribution creates a flywheel: more plugins attract more users across more platforms, more users attract more plugin creators from more domains, and the growing library of quality plugins reinforces BMAD's reputation as the curated alternative to the skills bazaar. BMAD evolves from a method into an ecosystem. diff --git a/src/module.yaml b/src/module.yaml index ed38ac4..4003333 100644 --- a/src/module.yaml +++ b/src/module.yaml @@ -3,6 +3,12 @@ name: "BMad Builder" description: "Standard Skill Compliant Factory for BMad Agents, Workflows and Modules" default_selected: false +# Variables from Core Config inserted: +## user_name +## communication_language +## document_output_language +## output_folder + bmad_builder_output_folder: prompt: "Where should your custom skills (agents and workflows) be saved?" default: "_bmad-output/skills" diff --git a/src/skills/bmad-agent-builder/SKILL.md b/src/skills/bmad-agent-builder/SKILL.md index d840ec5..177ca7f 100644 --- a/src/skills/bmad-agent-builder/SKILL.md +++ b/src/skills/bmad-agent-builder/SKILL.md @@ -40,7 +40,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 +48,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 +56,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/src/skills/bmad-agent-builder/agents/report-quality-scan-creator.md b/src/skills/bmad-agent-builder/agents/report-quality-scan-creator.md deleted file mode 100644 index a49a9ae..0000000 --- a/src/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/src/skills/bmad-agent-builder/templates/SKILL-template.md b/src/skills/bmad-agent-builder/assets/SKILL-template.md similarity index 87% rename from src/skills/bmad-agent-builder/templates/SKILL-template.md rename to src/skills/bmad-agent-builder/assets/SKILL-template.md index 9314e07..6bdec78 100644 --- a/src/skills/bmad-agent-builder/templates/SKILL-template.md +++ b/src/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/src/skills/bmad-agent-builder/templates/autonomous-wake.md b/src/skills/bmad-agent-builder/assets/autonomous-wake.md similarity index 100% rename from src/skills/bmad-agent-builder/templates/autonomous-wake.md rename to src/skills/bmad-agent-builder/assets/autonomous-wake.md diff --git a/src/skills/bmad-agent-builder/templates/init-template.md b/src/skills/bmad-agent-builder/assets/init-template.md similarity index 100% rename from src/skills/bmad-agent-builder/templates/init-template.md rename to src/skills/bmad-agent-builder/assets/init-template.md diff --git a/src/skills/bmad-agent-builder/templates/memory-system.md b/src/skills/bmad-agent-builder/assets/memory-system.md similarity index 98% rename from src/skills/bmad-agent-builder/templates/memory-system.md rename to src/skills/bmad-agent-builder/assets/memory-system.md index 1301c5b..8c3946c 100644 --- a/src/skills/bmad-agent-builder/templates/memory-system.md +++ b/src/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/src/skills/bmad-agent-builder/assets/quality-report-template.md b/src/skills/bmad-agent-builder/assets/quality-report-template.md new file mode 100644 index 0000000..b6811db --- /dev/null +++ b/src/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/src/skills/bmad-agent-builder/templates/save-memory.md b/src/skills/bmad-agent-builder/assets/save-memory.md similarity index 100% rename from src/skills/bmad-agent-builder/templates/save-memory.md rename to src/skills/bmad-agent-builder/assets/save-memory.md diff --git a/src/skills/bmad-agent-builder/bmad-manifest.json b/src/skills/bmad-agent-builder/bmad-manifest.json index eaa12bd..d9a6ace 100644 --- a/src/skills/bmad-agent-builder/bmad-manifest.json +++ b/src/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/src/skills/bmad-agent-builder/prompts/build-process.md b/src/skills/bmad-agent-builder/build-process.md similarity index 77% rename from src/skills/bmad-agent-builder/prompts/build-process.md rename to src/skills/bmad-agent-builder/build-process.md index 07ad158..4eb52cf 100644 --- a/src/skills/bmad-agent-builder/prompts/build-process.md +++ b/src/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/src/skills/bmad-agent-builder/prompts/quality-optimizer.md b/src/skills/bmad-agent-builder/quality-optimizer.md similarity index 79% rename from src/skills/bmad-agent-builder/prompts/quality-optimizer.md rename to src/skills/bmad-agent-builder/quality-optimizer.md index 28a7cfe..2e22591 100644 --- a/src/skills/bmad-agent-builder/prompts/quality-optimizer.md +++ b/src/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/src/skills/bmad-agent-builder/agents/quality-scan-agent-cohesion.md b/src/skills/bmad-agent-builder/quality-scan-agent-cohesion.md similarity index 77% rename from src/skills/bmad-agent-builder/agents/quality-scan-agent-cohesion.md rename to src/skills/bmad-agent-builder/quality-scan-agent-cohesion.md index 440ef71..66a8f17 100644 --- a/src/skills/bmad-agent-builder/agents/quality-scan-agent-cohesion.md +++ b/src/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/src/skills/bmad-agent-builder/agents/quality-scan-enhancement-opportunities.md b/src/skills/bmad-agent-builder/quality-scan-enhancement-opportunities.md similarity index 87% rename from src/skills/bmad-agent-builder/agents/quality-scan-enhancement-opportunities.md rename to src/skills/bmad-agent-builder/quality-scan-enhancement-opportunities.md index a9e179b..df2b565 100644 --- a/src/skills/bmad-agent-builder/agents/quality-scan-enhancement-opportunities.md +++ b/src/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/src/skills/bmad-agent-builder/agents/quality-scan-execution-efficiency.md b/src/skills/bmad-agent-builder/quality-scan-execution-efficiency.md similarity index 83% rename from src/skills/bmad-agent-builder/agents/quality-scan-execution-efficiency.md rename to src/skills/bmad-agent-builder/quality-scan-execution-efficiency.md index ba3e52e..a5b2201 100644 --- a/src/skills/bmad-agent-builder/agents/quality-scan-execution-efficiency.md +++ b/src/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/src/skills/bmad-agent-builder/agents/quality-scan-prompt-craft.md b/src/skills/bmad-agent-builder/quality-scan-prompt-craft.md similarity index 85% rename from src/skills/bmad-agent-builder/agents/quality-scan-prompt-craft.md rename to src/skills/bmad-agent-builder/quality-scan-prompt-craft.md index 1e9aa45..ee41330 100644 --- a/src/skills/bmad-agent-builder/agents/quality-scan-prompt-craft.md +++ b/src/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/src/skills/bmad-agent-builder/agents/quality-scan-script-opportunities.md b/src/skills/bmad-agent-builder/quality-scan-script-opportunities.md similarity index 89% rename from src/skills/bmad-agent-builder/agents/quality-scan-script-opportunities.md rename to src/skills/bmad-agent-builder/quality-scan-script-opportunities.md index 401c5d8..9e5de21 100644 --- a/src/skills/bmad-agent-builder/agents/quality-scan-script-opportunities.md +++ b/src/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/src/skills/bmad-agent-builder/agents/quality-scan-structure.md b/src/skills/bmad-agent-builder/quality-scan-structure.md similarity index 92% rename from src/skills/bmad-agent-builder/agents/quality-scan-structure.md rename to src/skills/bmad-agent-builder/quality-scan-structure.md index 24fdc1f..e7bceb2 100644 --- a/src/skills/bmad-agent-builder/agents/quality-scan-structure.md +++ b/src/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/src/skills/bmad-agent-builder/resources/metadata-reference.md b/src/skills/bmad-agent-builder/references/metadata-reference.md similarity index 91% rename from src/skills/bmad-agent-builder/resources/metadata-reference.md rename to src/skills/bmad-agent-builder/references/metadata-reference.md index 73ba3df..4a0b7e7 100644 --- a/src/skills/bmad-agent-builder/resources/metadata-reference.md +++ b/src/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/src/skills/bmad-agent-builder/resources/quality-dimensions.md b/src/skills/bmad-agent-builder/references/quality-dimensions.md similarity index 79% rename from src/skills/bmad-agent-builder/resources/quality-dimensions.md rename to src/skills/bmad-agent-builder/references/quality-dimensions.md index f79b595..064d17c 100644 --- a/src/skills/bmad-agent-builder/resources/quality-dimensions.md +++ b/src/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/src/skills/bmad-agent-builder/resources/script-opportunities-reference.md b/src/skills/bmad-agent-builder/references/script-opportunities-reference.md similarity index 97% rename from src/skills/bmad-agent-builder/resources/script-opportunities-reference.md rename to src/skills/bmad-agent-builder/references/script-opportunities-reference.md index d890f95..fecbed0 100644 --- a/src/skills/bmad-agent-builder/resources/script-opportunities-reference.md +++ b/src/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/src/skills/bmad-agent-builder/resources/skill-best-practices.md b/src/skills/bmad-agent-builder/references/skill-best-practices.md similarity index 98% rename from src/skills/bmad-agent-builder/resources/skill-best-practices.md rename to src/skills/bmad-agent-builder/references/skill-best-practices.md index 432a502..67cdeb3 100644 --- a/src/skills/bmad-agent-builder/resources/skill-best-practices.md +++ b/src/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/src/skills/bmad-agent-builder/resources/standard-fields.md b/src/skills/bmad-agent-builder/references/standard-fields.md similarity index 100% rename from src/skills/bmad-agent-builder/resources/standard-fields.md rename to src/skills/bmad-agent-builder/references/standard-fields.md diff --git a/src/skills/bmad-agent-builder/resources/template-substitution-rules.md b/src/skills/bmad-agent-builder/references/template-substitution-rules.md similarity index 94% rename from src/skills/bmad-agent-builder/resources/template-substitution-rules.md rename to src/skills/bmad-agent-builder/references/template-substitution-rules.md index b0e4a87..b3bce15 100644 --- a/src/skills/bmad-agent-builder/resources/template-substitution-rules.md +++ b/src/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/src/skills/bmad-agent-builder/references/universal-scan-schema.md b/src/skills/bmad-agent-builder/references/universal-scan-schema.md new file mode 100644 index 0000000..11e6df8 --- /dev/null +++ b/src/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/src/skills/bmad-agent-builder/report-quality-scan-creator.md b/src/skills/bmad-agent-builder/report-quality-scan-creator.md new file mode 100644 index 0000000..3a0376e --- /dev/null +++ b/src/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/src/skills/bmad-agent-builder/scripts/bmad-manifest-schema.json b/src/skills/bmad-agent-builder/scripts/bmad-manifest-schema.json index 90e66db..ea674b5 100644 --- a/src/skills/bmad-agent-builder/scripts/bmad-manifest-schema.json +++ b/src/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/src/skills/bmad-agent-builder/scripts/generate-html-report.py b/src/skills/bmad-agent-builder/scripts/generate-html-report.py new file mode 100644 index 0000000..a8614db --- /dev/null +++ b/src/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