initial commit
This commit is contained in:
208
.claude/skills/bmad-agent-builder/quality-optimizer.md
Normal file
208
.claude/skills/bmad-agent-builder/quality-optimizer.md
Normal file
@@ -0,0 +1,208 @@
|
||||
---
|
||||
name: quality-optimizer
|
||||
description: Comprehensive quality validation for BMad agents. Runs deterministic lint scripts and spawns parallel subagents for judgment-based scanning. Returns consolidated findings as structured JSON.
|
||||
menu-code: QO
|
||||
---
|
||||
|
||||
**Language:** Use `{communication_language}` for all output.
|
||||
|
||||
# Quality Optimizer
|
||||
|
||||
You orchestrate quality scans on a BMad agent. Deterministic checks run as scripts (fast, zero tokens). Judgment-based analysis runs as LLM subagents. You synthesize all results into a unified report.
|
||||
|
||||
## Your Role: Coordination, Not File Reading
|
||||
|
||||
**DO NOT read the target agent's files yourself.** Scripts and subagents do all analysis.
|
||||
|
||||
Your job:
|
||||
1. Create output directory
|
||||
2. Run all lint scripts + pre-pass scripts (instant, deterministic)
|
||||
3. Spawn all LLM scanner subagents in parallel (with pre-pass data where available)
|
||||
4. Collect all results
|
||||
5. Synthesize into unified report (spawn report creator)
|
||||
6. Present findings to user
|
||||
|
||||
## Autonomous Mode
|
||||
|
||||
**Check if `{headless_mode}=true`** — If set, run in headless mode:
|
||||
- **Skip ALL questions** — proceed with safe defaults
|
||||
- **Uncommitted changes:** Note in report, don't ask
|
||||
- **Agent functioning:** Assume yes, note in report that user should verify
|
||||
- **After report:** Output summary and exit, don't offer next steps
|
||||
- **Output format:** Structured JSON summary + report path, minimal conversational text
|
||||
|
||||
**Autonomous mode output:**
|
||||
```json
|
||||
{
|
||||
"headless_mode": true,
|
||||
"report_file": "{path-to-report}",
|
||||
"summary": { ... },
|
||||
"warnings": ["Uncommitted changes detected", "Agent functioning not verified"]
|
||||
}
|
||||
```
|
||||
|
||||
## Pre-Scan Checks
|
||||
|
||||
Before running any scans:
|
||||
|
||||
**IF `{headless_mode}=true`:**
|
||||
1. **Check for uncommitted changes** — Run `git status`. Note in warnings array if found.
|
||||
2. **Skip agent functioning verification** — Add to warnings: "Agent functioning not verified — user should confirm agent is working before applying fixes"
|
||||
3. **Proceed directly to scans**
|
||||
|
||||
**IF `{headless_mode}=false` or not set:**
|
||||
1. **Check for uncommitted changes** — Run `git status` on the repository. If uncommitted changes:
|
||||
- Warn: "You have uncommitted changes. It's recommended to commit before optimization so you can easily revert if needed."
|
||||
- Ask: "Do you want to proceed anyway, or commit first?"
|
||||
- Halt and wait for user response
|
||||
|
||||
2. **Verify agent is functioning** — Ask if the agent is currently working as expected. Optimization should improve, not break working agents.
|
||||
|
||||
## Communicate This Guidance to the User
|
||||
|
||||
**Agent skills are both art and science.** The report will contain many suggestions. Apply these decision rules:
|
||||
|
||||
- **Keep phrasing** that captures the agent's intended voice or personality — leaner isn't always better for persona-driven agents
|
||||
- **Keep content** that adds clarity for the AI even if a human would find it obvious — the AI needs explicit guidance
|
||||
- **Prefer scripting** for deterministic operations; **prefer prompting** for creative, contextual, or judgment-based tasks
|
||||
- **Reject changes** that would flatten the agent's personality unless the user explicitly wants a neutral tone
|
||||
|
||||
## Quality Scanners
|
||||
|
||||
### Lint Scripts (Deterministic — Run First)
|
||||
|
||||
These run instantly, cost zero tokens, and produce structured JSON:
|
||||
|
||||
| # | Script | Focus | Temp Filename |
|
||||
|---|--------|-------|---------------|
|
||||
| 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)
|
||||
|
||||
These extract metrics for the LLM scanners so they work from compact data instead of raw files:
|
||||
|
||||
| # | Script | Feeds | Temp Filename |
|
||||
|---|--------|-------|---------------|
|
||||
| P1 | `scripts/prepass-structure-capabilities.py` | structure LLM scanner | `structure-capabilities-prepass.json` |
|
||||
| P2 | `scripts/prepass-prompt-metrics.py` | prompt-craft LLM scanner | `prompt-metrics-prepass.json` |
|
||||
| P3 | `scripts/prepass-execution-deps.py` | execution-efficiency LLM scanner | `execution-deps-prepass.json` |
|
||||
|
||||
### LLM Scanners (Judgment-Based — Run After Scripts)
|
||||
|
||||
| # | Scanner | Focus | Pre-Pass? | Temp Filename |
|
||||
|---|---------|-------|-----------|---------------|
|
||||
| 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
|
||||
|
||||
First create output directory: `{bmad_builder_reports}/{skill-name}/quality-scan/{date-time-stamp}/`
|
||||
|
||||
### Step 1: Run Lint Scripts + Pre-Pass Scripts (Parallel)
|
||||
|
||||
Run all applicable scripts in parallel. They output JSON — capture to temp files in the output directory:
|
||||
|
||||
```bash
|
||||
# Full scan runs all 2 lint scripts + all 3 pre-pass scripts (5 total, all parallel)
|
||||
python3 scripts/scan-path-standards.py {skill-path} -o {quality-report-dir}/path-standards-temp.json
|
||||
python3 scripts/scan-scripts.py {skill-path} -o {quality-report-dir}/scripts-temp.json
|
||||
python3 scripts/prepass-structure-capabilities.py {skill-path} -o {quality-report-dir}/structure-capabilities-prepass.json
|
||||
python3 scripts/prepass-prompt-metrics.py {skill-path} -o {quality-report-dir}/prompt-metrics-prepass.json
|
||||
uv run scripts/prepass-execution-deps.py {skill-path} -o {quality-report-dir}/execution-deps-prepass.json
|
||||
```
|
||||
|
||||
### Step 2: Spawn LLM Scanners (Parallel)
|
||||
|
||||
After scripts complete, spawn applicable LLM scanners as parallel subagents.
|
||||
|
||||
**For scanners WITH pre-pass (L1, L2, L3):** provide the pre-pass JSON file path so the scanner reads compact metrics instead of raw files. The subagent should read the pre-pass JSON first, then only read raw files for judgment calls the pre-pass doesn't cover.
|
||||
|
||||
**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., `quality-scan-agent-cohesion.md`)
|
||||
- Skill path to scan: `{skill-path}`
|
||||
- Output directory for results: `{quality-report-dir}`
|
||||
- Temp filename for output: `{temp-filename}`
|
||||
- Pre-pass file path (if applicable): `{quality-report-dir}/{prepass-filename}`
|
||||
|
||||
The subagent will:
|
||||
- Load the scanner file and operate as that scanner
|
||||
- Read pre-pass JSON first if provided, then read raw files only as needed
|
||||
- Output findings as detailed JSON to: `{quality-report-dir}/{temp-filename}.json`
|
||||
- Return only the filename when complete
|
||||
|
||||
## Synthesis
|
||||
|
||||
After all scripts and scanners complete:
|
||||
|
||||
**IF only lint scripts ran (no LLM scanners):**
|
||||
1. Read the script output JSON files
|
||||
2. Present findings directly — these are definitive pass/fail results
|
||||
|
||||
**IF single LLM scanner (with or without scripts):**
|
||||
1. Read all temp JSON files (script + scanner)
|
||||
2. Present findings directly in simplified format
|
||||
3. Skip report creator (not needed for single scanner)
|
||||
|
||||
**IF multiple LLM scanners:**
|
||||
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:
|
||||
|
||||
**IF `{headless_mode}=true`:**
|
||||
1. **Output structured JSON:**
|
||||
```json
|
||||
{
|
||||
"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,
|
||||
"critical": 0,
|
||||
"high": 0,
|
||||
"medium": 0,
|
||||
"low": 0,
|
||||
"overall_quality": "{Excellent|Good|Fair|Poor}",
|
||||
"truly_broken_found": false
|
||||
}
|
||||
}
|
||||
```
|
||||
2. **Exit** — Don't offer next steps, don't ask questions
|
||||
|
||||
**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 reports** — "Full report: {report_file}" and "Interactive HTML report opened in browser (also at: {html_report})"
|
||||
4. **Offer next steps:**
|
||||
- Apply fixes directly
|
||||
- Use the HTML report to select specific items and generate prompts
|
||||
- Discuss specific findings
|
||||
|
||||
## Key Principle
|
||||
|
||||
Your role is ORCHESTRATION: run scripts, spawn subagents, synthesize results. Scripts handle deterministic checks (paths, schema, script standards). LLM scanners handle judgment calls (cohesion, craft, efficiency). You coordinate both and present unified findings.
|
||||
Reference in New Issue
Block a user