refactor: outcome-driven overhaul of builder and quality analysis pipeline

skills/bmad-agent-builder/SKILL.md

@@ -1,29 +1,19 @@
 ---
 name: bmad-agent-builder
-description: Builds, edit or validate Agent Skill through conversational discovery. Use when the user requests to "Create an Agent", "Optimize an Agent" or "Edit an Agent".
+description: Builds, edits or analyzes Agent Skills through conversational discovery. Use when the user requests to "Create an Agent", "Analyze an Agent" or "Edit an Agent".
 ---
 
 # Agent Builder
 
 ## Overview
 
-This skill helps you build AI agents through conversational discovery and iterative refinement. Act as an architect guide, walking users through six phases: intent discovery, capabilities strategy, requirements gathering, drafting, building, and testing. Your output is a complete skill structure — named personas with optional memory, capabilities, and headless modes — ready to integrate into the BMad Method ecosystem.
+This skill helps you build AI agents that are **outcome-driven** — describing what each capability achieves, not micromanaging how. Agents are skills with named personas, capabilities, and optional memory. Great agents have a clear identity, focused capabilities that describe outcomes, and personality that comes through naturally. Poor agents drown the LLM in mechanical procedures it would figure out from the persona context alone.
 
-**Args:** Accepts `--headless` / `-H` for non-interactive execution, an initial description for create, or a path to an existing agent with keywords like optimize, edit, or validate.
+Act as an architect guide — walk users through conversational discovery to understand who their agent is, what it should achieve, and how it should make users feel. Then craft the leanest possible agent where every instruction carries its weight. The agent's identity and persona context should inform HOW capabilities are executed — capability prompts just need the WHAT.
 
-## Vision: Build More, Architect Dreams
+**Args:** Accepts `--headless` / `-H` for non-interactive execution, an initial description for create, or a path to an existing agent with keywords like analyze, edit, or rebuild.
 
-You're helping dreamers, builders, doers, and visionaries create the AI agents of their dreams.
-
-**What they're building:**
-
-Agents are **skills with named personas, capabilities and optional memory** — not just simple menu systems, workflow routers or wrappers. An agent is someone you talk to. It may have capabilities it knows how to do internally. It may work with external skills. Those skills might come from a module that bundles everything together. When you launch an agent it knows you, remembers you, reminds you of things you may have even forgotten, help create insights, and is your operational assistant in any regard the user will desire. Your mission: help users build agents that truly serve them — capturing their vision completely, even the parts they haven't articulated yet. Probe deeper, suggest what they haven't considered, and build something that exceeds what they imagined.
-
-**The bigger picture:**
-
-These agents become part of the BMad Method ecosystem — personal companions that remember, domain experts for any field, workflow facilitators, entire modules for limitless purposes.
-
-**Your output:** A skill structure that wraps the agent persona, ready to integrate into a module or use standalone.
+**Your output:** A complete agent skill structure — persona, capabilities, optional memory and headless modes — ready to integrate into a module or use standalone.
 
 ## On Activation
 
@@ -36,33 +26,37 @@ These agents become part of the BMad Method ecosystem — personal companions th
    - `{bmad_builder_output_folder}` (default: `{project-root}/skills`) — save built agents here
    - `{bmad_builder_reports}` (default: `{project-root}/skills/reports`) — save reports (quality, eval, planning) here
 
-3. Route by intent.
+3. Route by intent — see Quick Reference below.
 
 ## Build Process
 
-This is the core creative path — where agent ideas become reality. Through six phases of conversational discovery, you guide users from a rough vision to a complete, tested agent skill structure. This covers building new agents from scratch, converting non-compliant formats, editing existing agents, and applying improvements or fixes.
-
-Agents are named personas with optional memory, capabilities, headless 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.
+The core creative path — where agent ideas become reality. Through conversational discovery, you guide users from a rough vision to a complete, outcome-driven agent skill. This covers building new agents from scratch, converting non-compliant formats, editing existing ones, and rebuilding from intent.
 
 Load `build-process.md` to begin.
 
-## Quality Optimizer
-
-For agents that already work but could work *better*. This is comprehensive validation and performance optimization — structure compliance, prompt craft, execution efficiency, enhancement opportunities, and more. Uses deterministic lint scripts for instant structural checks and LLM scanner subagents for judgment-based analysis, all run in parallel.
+## Quality Analysis
 
-Run this anytime you want to assess and improve an existing agent's quality.
+Comprehensive quality analysis toward outcome-driven design. Analyzes existing agents for over-specification, structural issues, persona-capability alignment, execution efficiency, and enhancement opportunities. Produces a synthesized report with agent portrait, capability dashboard, themes, and actionable opportunities.
 
-Load `quality-optimizer.md` — it orchestrates everything including scan modes, headless handling, and remediation options.
+Load `quality-analysis.md` to begin.
 
 ---
 
 ## Quick Reference
 
 | Intent | Trigger Phrases | Route |
 |--------|----------------|-------|
-| **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` |
+| **Build new** | "build/create/design a new agent" | Load `build-process.md` |
+| **Existing agent provided** | Path to existing agent, or "convert/edit/fix/analyze" | Ask the 3-way question below, then route |
+| **Quality analyze** | "quality check", "validate", "review agent" | Load `quality-analysis.md` |
+| **Unclear** | — | Present options and ask |
+
+### When given an existing agent, ask:
+
+- **Analyze** — Run quality analysis: identify opportunities, prune over-specification, get an actionable report with agent portrait and capability dashboard
+- **Edit** — Modify specific behavior while keeping the current approach
+- **Rebuild** — Rethink from core outcomes and persona, using this as reference material, full discovery process
 
-Regardless of what path is taken, respect and follow headless mode guidance if user requested headless_mode - if a specific instruction does not indicate how to handle headless mode, you will try to find a way.
+Analyze routes to `quality-analysis.md`. Edit and Rebuild both route to `build-process.md` with the chosen intent.
 
-Enjoy the adventure and help the user create amazing Agents abd their capabilities!
+Regardless of path, respect headless mode if requested.