Skip to content

Refactor/flatten skill structure#30

Merged
bmadcode merged 6 commits intomainfrom
refactor/flatten-skill-structure
Mar 16, 2026
Merged

Refactor/flatten skill structure#30
bmadcode merged 6 commits intomainfrom
refactor/flatten-skill-structure

Conversation

@bmadcode
Copy link
Contributor

@bmadcode bmadcode commented Mar 16, 2026

Summary by CodeRabbit

  • New Features

    • Added interactive HTML quality reports with severity filtering and batch prompt generation.
  • Refactor

    • Reorganized skill file structure: capability prompts moved to root level; internal references consolidated to a dedicated references directory.
    • Standardized quality scan output schema across all scanners for consistent reporting.
  • Removed Features

    • Removed product-brief-preview skill and associated capabilities.
    • Removed BMM manifest skill registration.
  • Chores

    • Updated file path references throughout skill definitions to reflect new directory layout.

bmadcode and others added 5 commits March 15, 2026 16:40
- Move prompts/ and agents/ files to skill root (both builders)
- Rename templates/ to assets/ (both builders)
- Rename resources/ to references/ to match agentskills.io spec
- Remove unused tests/fixtures directories and skip guards
- Update all path references across SKILL.md, build-process, quality-optimizer,
  quality scanners, reference docs, templates, and Python scripts
- Add clear "what goes where" guidance table for root vs references vs assets vs scripts
- Builders now produce output skills following the same conventions

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Move prompts/ and agents/ files to skill root in all three samples
- Rename resources/ to references/
- Update all internal path references

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
…ructure

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
- Remove {skill-root} convention check from scanners and all reference docs
- Fix f-string lint errors (F541) in manifest.py and prepass-workflow-integrity.py
- Update stale pip install message to reference uv run with PEP 723
- Add {communication_language} config header to quality-optimizer.md
- Batch sequential file reads into parallel operations in all 6 scanner process sections
- Prior uncommitted improvements: HTML report generation, scan schema updates, scanner prompt refinements

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@augmentcode
Copy link

augmentcode bot commented Mar 16, 2026

This pull request is too large for Augment to review. The PR exceeds the maximum size limit of 100000 tokens (approximately 400000 characters) for automated code review. Please consider breaking this PR into smaller, more focused changes.

@coderabbitai
Copy link

coderabbitai bot commented Mar 16, 2026

Caution

Review failed

The pull request is closed.

ℹ️ Recent review info
⚙️ Run configuration

Configuration used: Organization UI

Review profile: CHILL

Plan: Pro

Run ID: 4a14e36e-89c4-4ee9-9850-1501bc58eae3

📥 Commits

Reviewing files that changed from the base of the PR and between c68f6b3 and a9de13b.

📒 Files selected for processing (106)
  • samples/bmad-agent-dream-weaver/SKILL.md
  • samples/bmad-agent-dream-weaver/bmad-manifest.json
  • samples/bmad-agent-dream-weaver/dream-interpret.md
  • samples/bmad-agent-dream-weaver/dream-log.md
  • samples/bmad-agent-dream-weaver/dream-query.md
  • samples/bmad-agent-dream-weaver/dream-seed.md
  • samples/bmad-agent-dream-weaver/headless-wake.md
  • samples/bmad-agent-dream-weaver/init.md
  • samples/bmad-agent-dream-weaver/lucid-coach.md
  • samples/bmad-agent-dream-weaver/pattern-discovery.md
  • samples/bmad-agent-dream-weaver/recall-training.md
  • samples/bmad-agent-dream-weaver/references/memory-system.md
  • samples/bmad-agent-dream-weaver/save-memory.md
  • samples/bmad-bmm-product-brief-preview/SKILL.md
  • samples/bmad-bmm-product-brief-preview/agents/artifact-analyzer.md
  • samples/bmad-bmm-product-brief-preview/agents/opportunity-reviewer.md
  • samples/bmad-bmm-product-brief-preview/agents/skeptic-reviewer.md
  • samples/bmad-bmm-product-brief-preview/agents/web-researcher.md
  • samples/bmad-bmm-product-brief-preview/bmad-manifest.json
  • samples/bmad-bmm-product-brief-preview/prompts/contextual-discovery.md
  • samples/bmad-bmm-product-brief-preview/prompts/draft-and-review.md
  • samples/bmad-bmm-product-brief-preview/prompts/finalize.md
  • samples/bmad-bmm-product-brief-preview/prompts/guided-elicitation.md
  • samples/bmad-bmm-product-brief-preview/resources/brief-template.md
  • samples/bmad-excalidraw/SKILL.md
  • samples/bmad-excalidraw/bmad-manifest.json
  • samples/bmad-excalidraw/diagram-generation.md
  • samples/bmad-excalidraw/guided-design.md
  • samples/bmad-excalidraw/references/diagram-types.md
  • samples/bmad-excalidraw/references/excalidraw-schema.md
  • samples/planning-artifacts/bmad-distillation-generator-spec.md
  • samples/planning-artifacts/product-brief-bmad-next-gen-installer-discovery-notes.md
  • samples/planning-artifacts/product-brief-bmad-next-gen-installer-distillate.md
  • samples/planning-artifacts/product-brief-bmad-next-gen-installer.md
  • src/module.yaml
  • src/skills/bmad-agent-builder/SKILL.md
  • src/skills/bmad-agent-builder/agents/report-quality-scan-creator.md
  • src/skills/bmad-agent-builder/assets/SKILL-template.md
  • src/skills/bmad-agent-builder/assets/autonomous-wake.md
  • src/skills/bmad-agent-builder/assets/init-template.md
  • src/skills/bmad-agent-builder/assets/memory-system.md
  • src/skills/bmad-agent-builder/assets/quality-report-template.md
  • src/skills/bmad-agent-builder/assets/save-memory.md
  • src/skills/bmad-agent-builder/bmad-manifest.json
  • src/skills/bmad-agent-builder/build-process.md
  • src/skills/bmad-agent-builder/quality-optimizer.md
  • src/skills/bmad-agent-builder/quality-scan-agent-cohesion.md
  • src/skills/bmad-agent-builder/quality-scan-enhancement-opportunities.md
  • src/skills/bmad-agent-builder/quality-scan-execution-efficiency.md
  • src/skills/bmad-agent-builder/quality-scan-prompt-craft.md
  • src/skills/bmad-agent-builder/quality-scan-script-opportunities.md
  • src/skills/bmad-agent-builder/quality-scan-structure.md
  • src/skills/bmad-agent-builder/references/metadata-reference.md
  • src/skills/bmad-agent-builder/references/quality-dimensions.md
  • src/skills/bmad-agent-builder/references/script-opportunities-reference.md
  • src/skills/bmad-agent-builder/references/skill-best-practices.md
  • src/skills/bmad-agent-builder/references/standard-fields.md
  • src/skills/bmad-agent-builder/references/template-substitution-rules.md
  • src/skills/bmad-agent-builder/references/universal-scan-schema.md
  • src/skills/bmad-agent-builder/report-quality-scan-creator.md
  • src/skills/bmad-agent-builder/scripts/bmad-manifest-schema.json
  • src/skills/bmad-agent-builder/scripts/generate-html-report.py
  • src/skills/bmad-agent-builder/scripts/prepass-execution-deps.py
  • src/skills/bmad-agent-builder/scripts/prepass-prompt-metrics.py
  • src/skills/bmad-agent-builder/scripts/prepass-structure-capabilities.py
  • src/skills/bmad-agent-builder/scripts/scan-path-standards.py
  • src/skills/bmad-agent-builder/scripts/scan-scripts.py
  • src/skills/bmad-agent-builder/tests/fixtures/complex/old-format-pm-agent.md
  • src/skills/bmad-agent-builder/tests/fixtures/deficient/bmad-agent-with-issues.md
  • src/skills/bmad-agent-builder/tests/test-validate-manifest.py
  • src/skills/bmad-bmb-manifest/SKILL.md
  • src/skills/bmad-bmb-manifest/bmad-skill-manifest.yaml
  • src/skills/bmad-workflow-builder/SKILL.md
  • src/skills/bmad-workflow-builder/agents/report-quality-scan-creator.md
  • src/skills/bmad-workflow-builder/assets/SKILL-template.md
  • src/skills/bmad-workflow-builder/assets/quality-report-template.md
  • src/skills/bmad-workflow-builder/bmad-manifest.json
  • src/skills/bmad-workflow-builder/build-process.md
  • src/skills/bmad-workflow-builder/quality-optimizer.md
  • src/skills/bmad-workflow-builder/quality-scan-enhancement-opportunities.md
  • src/skills/bmad-workflow-builder/quality-scan-execution-efficiency.md
  • src/skills/bmad-workflow-builder/quality-scan-prompt-craft.md
  • src/skills/bmad-workflow-builder/quality-scan-script-opportunities.md
  • src/skills/bmad-workflow-builder/quality-scan-skill-cohesion.md
  • src/skills/bmad-workflow-builder/quality-scan-workflow-integrity.md
  • src/skills/bmad-workflow-builder/references/classification-reference.md
  • src/skills/bmad-workflow-builder/references/complex-workflow-patterns.md
  • src/skills/bmad-workflow-builder/references/metadata-reference.md
  • src/skills/bmad-workflow-builder/references/quality-dimensions.md
  • src/skills/bmad-workflow-builder/references/script-opportunities-reference.md
  • src/skills/bmad-workflow-builder/references/skill-best-practices.md
  • src/skills/bmad-workflow-builder/references/standard-fields.md
  • src/skills/bmad-workflow-builder/references/template-substitution-rules.md
  • src/skills/bmad-workflow-builder/references/universal-scan-schema.md
  • src/skills/bmad-workflow-builder/report-quality-scan-creator.md
  • src/skills/bmad-workflow-builder/scripts/bmad-manifest-schema.json
  • src/skills/bmad-workflow-builder/scripts/generate-html-report.py
  • src/skills/bmad-workflow-builder/scripts/manifest.py
  • src/skills/bmad-workflow-builder/scripts/prepass-execution-deps.py
  • src/skills/bmad-workflow-builder/scripts/prepass-prompt-metrics.py
  • src/skills/bmad-workflow-builder/scripts/prepass-workflow-integrity.py
  • src/skills/bmad-workflow-builder/scripts/scan-path-standards.py
  • src/skills/bmad-workflow-builder/scripts/scan-scripts.py
  • src/skills/bmad-workflow-builder/tests/fixtures/complex/SKILL.md
  • src/skills/bmad-workflow-builder/tests/fixtures/complex/bmad-manifest.json
  • src/skills/bmad-workflow-builder/tests/fixtures/deficient/SKILL.md

Walkthrough

This pull request systematically refactors file organization and standardization across multiple BMAD skills: moving prompt files from subdirectories to root level, replacing resources/ with references/, eliminating obsolete skill specifications, introducing unified scanner output schemas, adding HTML report generation, and integrating external linting tools.

Changes

Cohort / File(s) Summary
Path Reorganization (prompts/ → root, resources/ → references/)
samples/bmad-agent-dream-weaver/SKILL.md, samples/bmad-agent-dream-weaver/bmad-manifest.json, samples/bmad-agent-dream-weaver/references/memory-system.md, samples/bmad-excalidraw/*, src/skills/bmad-agent-builder/* (SKILL.md, bmad-manifest.json, build-process.md, quality-optimizer.md, assets/, references/), src/skills/bmad-workflow-builder/* (SKILL.md, bmad-manifest.json, build-process.md, quality-optimizer.md, assets/, references/)
Systematic refactoring: removes prompts/ prefix from prompt file paths (e.g., prompts/build-process.mdbuild-process.md), migrates resources/ references to references/, and removes {skill-root} token usage. Affects manifest files, documentation, and internal file references across all skills.
Scanner Output Schema Standardization
src/skills/bmad-agent-builder/quality-scan-*.md, src/skills/bmad-workflow-builder/quality-scan-*.md, src/skills/bmad-agent-builder/references/universal-scan-schema.md, src/skills/bmad-workflow-builder/references/universal-scan-schema.md
Introduces unified scanner JSON schema with standardized finding fields (file, line, severity, category, title, detail, action), replaces heterogeneous output structures with consistent findings array and assessments object, adds severity values including "strength", and reworks summaries to use total_findings instead of total_issues.
Quality Report Template & Metadata
src/skills/bmad-agent-builder/assets/quality-report-template.md, src/skills/bmad-workflow-builder/assets/quality-report-template.md, src/skills/bmad-agent-builder/report-quality-scan-creator.md, src/skills/bmad-workflow-builder/report-quality-scan-creator.md
Adds comprehensive quality report templates with placeholder-driven sections (executive summary, findings by category, user journeys, autonomous readiness), defines template population rules, deduplication strategy, and scanner-to-temp-file mappings for unified report generation.
HTML Report & Script Generation
src/skills/bmad-agent-builder/scripts/generate-html-report.py, src/skills/bmad-workflow-builder/scripts/generate-html-report.py
New 1000+ line Python scripts that load scanner temp files, normalize findings across diverse scanner outputs, build user journeys, compute quality grades, generate self-contained interactive HTML reports with filtering/selection/batch-prompt features, and support CLI arguments for skill-path detection and browser opening.
Linting Tool Integration
src/skills/bmad-agent-builder/scripts/scan-scripts.py, src/skills/bmad-workflow-builder/scripts/scan-scripts.py
Adds external linter runners (ruff for Python, shellcheck for Bash, biome for JS/TS), implements JS/TS script version-pinning checks, integrates lint findings into main scanner output, tracks lint-tool usage under new lint_summary assessments, and bumps scanner version to 2.0.0.
Prepass & Path Scanning Updates
src/skills/bmad-agent-builder/scripts/prepass-*.py, src/skills/bmad-workflow-builder/scripts/prepass-*.py, src/skills/bmad-agent-builder/scripts/scan-path-standards.py, src/skills/bmad-workflow-builder/scripts/scan-path-standards.py
Updates prompt/stage discovery from prompts/ subdirectory to root-level .md files, adjusts subagent detection heuristics, removes {skill-root} pattern checks, migrates output from issues to findings structure, adds assessments container, and refactors relative path handling.
Deletion: bmad-bmm-product-brief-preview Skill
samples/bmad-bmm-product-brief-preview/SKILL.md, samples/bmad-bmm-product-brief-preview/bmad-manifest.json, samples/bmad-bmm-product-brief-preview/agents/*, samples/bmad-bmm-product-brief-preview/prompts/*, samples/bmad-bmm-product-brief-preview/resources/brief-template.md
Removes entire product-brief skill specification including capability definitions, multi-stage workflow prompts (contextual-discovery, guided-elicitation, draft-and-review, finalize), agent analyzers (artifact, opportunity-reviewer, skeptic-reviewer, web-researcher), and resource templates.
Deletion: Obsolete Manifests & Specifications
src/skills/bmad-bmb-manifest/SKILL.md, src/skills/bmad-bmb-manifest/bmad-skill-manifest.yaml, samples/planning-artifacts/bmad-distillation-generator-spec.md, samples/planning-artifacts/product-brief-bmad-next-gen-installer*.md
Removes bmad-bmb-manifest skill registration, eliminates obsolete planning documents for distillation generator and next-gen installer discovery/product briefs.
Deletion: Test Fixtures & Old Documentation
src/skills/bmad-agent-builder/agents/report-quality-scan-creator.md, src/skills/bmad-agent-builder/tests/fixtures/*/, src/skills/bmad-agent-builder/tests/test-validate-manifest.py, src/skills/bmad-workflow-builder/agents/report-quality-scan-creator.md, src/skills/bmad-workflow-builder/tests/fixtures/*/
Removes old agent documentation (report-quality-scan-creator moved from agents/ to root), deletes complex/deficient workflow fixtures, and removes manifest validation test suite.
Module Config & Metadata Updates
src/module.yaml, src/skills/bmad-agent-builder/references/metadata-reference.md, src/skills/bmad-agent-builder/references/quality-dimensions.md, src/skills/bmad-agent-builder/references/template-substitution-rules.md, src/skills/bmad-workflow-builder/references/*
Adds core config variable documentation, introduces result paths for builder output and reports, updates metadata reference paths, refines path construction rules, and synchronizes reference documentation across both builder skills.
Schema & Script Examples
src/skills/bmad-agent-builder/scripts/bmad-manifest-schema.json, src/skills/bmad-workflow-builder/scripts/bmad-manifest-schema.json, src/skills/bmad-workflow-builder/scripts/prepass-execution-deps.py, src/skills/bmad-workflow-builder/scripts/prepass-workflow-integrity.py, src/skills/bmad-workflow-builder/scripts/manifest.py
Updates manifest schema example paths (removes prompts/ prefix), refines workflow integrity checks for root-level stage prompts, adjusts subagent detection logic, and updates error messaging for tool dependencies.

Sequence Diagram(s)

sequenceDiagram
    participant Scanner as LLM Scanners
    participant TempFiles as Temp JSON Files
    participant Normalizer as generate-html-report.py
    participant Template as quality-report-template.md
    participant HTML as Interactive HTML
    
    Scanner->>TempFiles: Write findings (diverse schemas)
    Normalizer->>TempFiles: Load *-temp.json & *-prepass.json
    Normalizer->>Normalizer: Normalize findings to universal schema
    Normalizer->>Normalizer: Compute quality grade from severities
    Normalizer->>Normalizer: Extract user journeys & assessments
    Normalizer->>Template: Populate template with normalized data
    Template->>HTML: Render with severity filters & interactive UI
    HTML->>HTML: Client-side filtering, selection, batch prompts
Loading
sequenceDiagram
    participant Skill as Skill Directory
    participant Scripts as Prepass/Scanner Scripts
    participant Findings as Findings Array
    participant Assessment as Assessments Object
    participant Output as JSON Output
    
    Skill->>Scripts: Scan root .md files (no prompts/ subdirectory)
    Skill->>Scripts: Scan references/ (no resources/)
    Scripts->>Scripts: Run linters (ruff, shellcheck, biome)
    Scripts->>Findings: Normalize to [file, line, severity, category, title, detail, action]
    Scripts->>Assessment: Collect cohesion, prompt_health, lint_summary, user_journeys
    Findings->>Output: Write findings array
    Assessment->>Output: Write assessments object
    Output->>Output: Include summary with total_findings, by_severity, assessment
Loading

Estimated code review effort

🎯 4 (Complex) | ⏱️ ~75 minutes


Poem

🐰 Files reorganized from deep nested trees,
To roots and references, skills now breathe with ease.
New schemas unified, findings aligned,
HTML reports sparkle—intelligence refined!
One great refactoring hops on through. 🌟

✨ Finishing Touches
  • 📝 Generate docstrings (stacked PR)
  • 📝 Generate docstrings (commit on current branch)
🧪 Generate unit tests (beta)
  • Create PR with unit tests
  • Post copyable unit tests in a comment
  • Commit unit tests in branch refactor/flatten-skill-structure

Co-Authored-By: Claude Opus 4.6 (1M context) <noreply@anthropic.com>
@bmadcode bmadcode merged commit 4a79058 into main Mar 16, 2026
0 of 5 checks passed
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

1 participant