bmad-method-quarkus 1.0.0

package/src/bmm-skills/agents/bmad-quarkus-architect/skills/bqa-setup/SKILL.md

@@ -0,0 +1,80 @@
+---
+name: "bqa-setup"
+description: Sets up BMad Quarkus Architect module in a project. Use when the user requests to 'install bqa module', 'configure BMad Quarkus Architect', or 'setup BMad Quarkus Architect'.
+---
+
+# Module Setup
+
+## Overview
+
+Installs and configures a BMad module into a project. Module identity (name, code, version) comes from `./assets/module.yaml`. Collects user preferences and writes them to three files:
+
+- **`{project-root}/_bmad/config.yaml`** — shared project config: core settings at root (e.g. `output_folder`, `document_output_language`) plus a section per module with metadata and module-specific values. User-only keys (`user_name`, `communication_language`) are **never** written here.
+- **`{project-root}/_bmad/config.user.yaml`** — personal settings intended to be gitignored: `user_name`, `communication_language`, and any module variable marked `user_setting: true` in `./assets/module.yaml`. These values live exclusively here.
+- **`{project-root}/_bmad/module-help.csv`** — registers module capabilities for the help system.
+
+Both config scripts use an anti-zombie pattern — existing entries for this module are removed before writing fresh ones, so stale values never persist.
+
+`{project-root}` is a **literal token** in config _values_ (the data written into the files above) — never substitute it there. It signals to the consuming LLM that the value is relative to the project root, not the skill root. **This does not apply to the filesystem path _arguments_ passed to the scripts below** (the `--*-path`, `--*-dir`, and `--target` arguments): those are real paths, so you **must** resolve `{project-root}` to the actual project root before running, or the scripts will write to a literal `{project-root}/` directory under the skill folder. The scripts reject an unresolved token with an error.
+
+## On Activation
+
+1. Read `./assets/module.yaml` for module metadata and variable definitions (the `code` field is the module identifier)
+2. Check if `{project-root}/_bmad/config.yaml` exists — if a section matching the module's code is already present, inform the user this is an update
+3. Check for per-module configuration at `{project-root}/_bmad/bqa/config.yaml` and `{project-root}/_bmad/core/config.yaml`. If either file exists:
+   - If `{project-root}/_bmad/config.yaml` does **not** yet have a section for this module: this is a **fresh install**. Inform the user that installer config was detected and values will be consolidated into the new format.
+   - If `{project-root}/_bmad/config.yaml` **already** has a section for this module: this is a **legacy migration**. Inform the user that legacy per-module config was found alongside existing config, and legacy values will be used as fallback defaults.
+   - In both cases, per-module config files and directories will be cleaned up after setup.
+
+If the user provides arguments (e.g. `accept all defaults`, `--headless`, or inline values like `user name is BMad, I speak Swahili`), map any provided values to config keys, use defaults for the rest, and skip interactive prompting. Still display the full confirmation summary at the end.
+
+## Collect Configuration
+
+Ask the user for values. Show defaults in brackets. Present all values together so the user can respond once with only the values they want to change (e.g. "change language to Swahili, rest are fine"). Never tell the user to "press enter" or "leave blank" — in a chat interface they must type something to respond.
+
+**Default priority** (highest wins): existing new config values > legacy config values > `./assets/module.yaml` defaults. When legacy configs exist, read them and use matching values as defaults instead of `module.yaml` defaults. Only keys that match the current schema are carried forward — changed or removed keys are ignored.
+
+**Core config** (only if no core keys exist yet): `user_name` (default: BMad), `communication_language` and `document_output_language` (default: English — ask as a single language question, both keys get the same answer), `output_folder` (default: `{project-root}/_bmad-output`). Of these, `user_name` and `communication_language` are written exclusively to `config.user.yaml`. The rest go to `config.yaml` at root and are shared across all modules.
+
+**Module config**: Read each variable in `./assets/module.yaml` that has a `prompt` field. Ask using that prompt with its default value (or legacy value if available).
+
+## Write Files
+
+Write a temp JSON file with the collected answers structured as `{"core": {...}, "module": {...}}` (omit `core` if it already exists). Values inside this JSON keep the literal `{project-root}` token. Then run both scripts — they can run in parallel since they write to different files.
+
+In the commands below, replace `{project-root}` in every path argument with the actual project root (e.g. `/home/me/myapp`) before running — these are filesystem paths, not config values.
+
+```bash
+uv run ./scripts/merge-config.py --config-path "{project-root}/_bmad/config.yaml" --user-config-path "{project-root}/_bmad/config.user.yaml" --module-yaml ./assets/module.yaml --answers {temp-file} --legacy-dir "{project-root}/_bmad"
+uv run ./scripts/merge-help-csv.py --target "{project-root}/_bmad/module-help.csv" --source ./assets/module-help.csv --legacy-dir "{project-root}/_bmad" --module-code bqa
+```
+
+Both scripts output JSON to stdout with results. If either exits non-zero, surface the error and stop. The scripts automatically read legacy config values as fallback defaults, then delete the legacy files after a successful merge. Check `legacy_configs_deleted` and `legacy_csvs_deleted` in the output to confirm cleanup.
+
+Run `./scripts/merge-config.py --help` or `./scripts/merge-help-csv.py --help` for full usage.
+
+## Create Output Directories
+
+After writing config, create any output directories that were configured. For filesystem operations only (such as creating directories), resolve the `{project-root}` token to the actual project root and create each path-type value from `config.yaml` that does not yet exist — this includes `output_folder` and any module variable whose value starts with `{project-root}/`. The paths stored in the config files must continue to use the literal `{project-root}` token; only the directories on disk should use the resolved paths. Use `mkdir -p` or equivalent to create the full path.
+
+## Cleanup Legacy Directories
+
+After both merge scripts complete successfully, remove the installer's package directories. Skills and agents in these directories are already installed at `.claude/skills/` — the `_bmad/` directory should only contain config files.
+
+As with the merge scripts, replace `{project-root}` in the `--bmad-dir` and `--skills-dir` path arguments with the actual project root before running.
+
+```bash
+uv run ./scripts/cleanup-legacy.py --bmad-dir "{project-root}/_bmad" --module-code bqa --also-remove _config --skills-dir "{project-root}/.claude/skills"
+```
+
+The script verifies that every skill in the legacy directories exists at `.claude/skills/` before removing anything. Directories without skills (like `_config/`) are removed directly. If the script exits non-zero, surface the error and stop. Missing directories (already cleaned by a prior run) are not errors — the script is idempotent.
+
+Check `directories_removed` and `files_removed_count` in the JSON output for the confirmation step. Run `./scripts/cleanup-legacy.py --help` for full usage.
+
+## Confirm
+
+Use the script JSON output to display what was written — config values set (written to `config.yaml` at root for core, module section for module values), user settings written to `config.user.yaml` (`user_keys` in result), help entries added, fresh install vs update. If legacy files were deleted, mention the migration. If legacy directories were removed, report the count and list (e.g. "Cleaned up 106 installer package files from bmb/, core/, \_config/ — skills are installed at .claude/skills/"). Then display the `module_greeting` from `./assets/module.yaml` to the user.
+
+## Outcome
+
+Once the user's `user_name` and `communication_language` are known (from collected input, arguments, or existing config), use them consistently for the remainder of the session: address the user by their configured name and communicate in their configured `communication_language`.

package/src/bmm-skills/agents/bmad-quarkus-architect/skills/bqa-setup/assets/module-help.csv

@@ -0,0 +1,9 @@
+module,skill,display-name,menu-code,description,action,args,phase,preceded-by,followed-by,required,output-location,outputs
+BMad Quarkus Architect,quarkus-hexagonal-core,Hexagonal Core Standard,HC,"Foundation hexagonal architecture, class naming conventions, monorepo layout, and ArchUnit rules for Quarkus/Java backend services. Auto-triggers whenever creating, scaffolding, or reviewing any service, endpoint, repository, use case, or domain class — the other standards below build on it.",,,anytime,,,false,,architecture guidance applied to code
+BMad Quarkus Architect,quarkus-error-handling-i18n,Error Handling & i18n,EH,"Unified global exception handler and internationalized (TMF630-aligned) API error responses. Auto-triggers on any exception handling, error response, or REST endpoint that can fail.",,,anytime,,,false,,architecture guidance applied to code
+BMad Quarkus Architect,quarkus-kafka-messaging,Kafka Messaging,KM,"CloudEvents envelope, topic naming, transactional outbox, idempotent consumers, and DLQ standard for asynchronous Kafka messaging. Auto-triggers on events, producers, consumers, or async integration between services.",,,anytime,,,false,,architecture guidance applied to code
+BMad Quarkus Architect,quarkus-grpc-services,gRPC Services,GS,"Standard for internal service-to-service gRPC calls — proto conventions, Mutiny services/clients, deadlines, error mapping. Auto-triggers on gRPC, protobuf, or internal synchronous service call mentions.",,,anytime,,,false,,architecture guidance applied to code
+BMad Quarkus Architect,quarkus-openapi-tmforum,OpenAPI / TM Forum,OT,"REST API design and documentation standard aligned to TM Forum Open API specs — pagination, filtering, JSON Merge Patch, Swagger dev/test-only. Auto-triggers on any REST resource creation or API design mention.",,,anytime,,,false,,architecture guidance applied to code
+BMad Quarkus Architect,quarkus-observability-otel,Observability (OTel),OB,"OpenTelemetry tracing, trace/span-id log correlation, OTLP export, and Micrometer metrics standard across REST/gRPC/Kafka. Auto-triggers on tracing, logging, or metrics mentions.",,,anytime,,,false,,architecture guidance applied to code
+BMad Quarkus Architect,quarkus-sql-jdbc-agroal,SQL/JDBC (Agroal),SJ,"Plain JDBC persistence standard via Agroal — no ORM, no Panache. Covers pooling, transactions, batches, jsonb, pagination. Auto-triggers on any repository, DAO, or SQL statement work.",,,anytime,,,false,,architecture guidance applied to code
+BMad Quarkus Architect,quarkus-architect,Quarkus Architecture Review (Elena),QR,"Elena, the Backend Standards Architect, reviews epics/stories right after they're written and enriches each with hexagonal-architecture placement, naming, and whichever persistence/gRPC/Kafka/REST/observability/error-handling standards apply — before sprint planning and build.",,,plan,bmad-create-epics-and-stories,bmad-sprint-planning,false,planning_artifacts,epics/stories enriched with a Quarkus Architecture Notes section

package/src/bmm-skills/agents/bmad-quarkus-architect/skills/bqa-setup/assets/module.yaml

@@ -0,0 +1,16 @@
+code: bqa
+name: "BMad Quarkus Architect"
+description: "Java/Quarkus hexagonal-architecture standards suite — persistence, messaging, gRPC, REST/TM Forum, observability, and error-handling conventions for native-compiled backend services, plus Elena, an agent that gates epics/stories with this guidance before implementation."
+module_version: 1.0.0
+default_selected: false
+module_greeting: >
+  BMad Quarkus Architect is active — these skills auto-trigger whenever you scaffold, write, or review Quarkus backend code. Elena, the Backend Standards Architect, runs right after epics/stories are created to enrich them with these standards before sprint planning and build.
+
+  Run this again at any time if you want to reconfigure a setting or have updated the module.
+
+agents:
+  - code: quarkus-architect
+    name: Elena
+    title: Backend Standards Architect
+    icon: "⬢"
+    description: "Reviews freshly created epics/stories and enriches each with Quarkus/Java backend architecture guidance — hexagonal layer placement, naming, and the relevant persistence/gRPC/Kafka/REST/observability/error-handling standards — before sprint planning and build."

package/src/bmm-skills/agents/bmad-quarkus-architect/skills/bqa-setup/scripts/cleanup-legacy.py

@@ -0,0 +1,287 @@
+#!/usr/bin/env python3
+# /// script
+# requires-python = ">=3.9"
+# dependencies = []
+# ///
+"""Remove legacy module directories from _bmad/ after config migration.
+
+After merge-config.py and merge-help-csv.py have migrated config data and
+deleted individual legacy files, this script removes the now-redundant
+directory trees. These directories contain skill files that are already
+installed at .claude/skills/ (or equivalent) — only the config files at
+_bmad/ root need to persist.
+
+When --skills-dir is provided, the script verifies that every skill found
+in the legacy directories exists at the installed location before removing
+anything. Directories without skills (like _config/) are removed directly.
+
+Exit codes: 0=success (including nothing to remove), 1=validation error, 2=runtime error
+"""
+
+import argparse
+import json
+import shutil
+import sys
+from pathlib import Path
+
+
+def parse_args():
+    parser = argparse.ArgumentParser(
+        description="Remove legacy module directories from _bmad/ after config migration."
+    )
+    parser.add_argument(
+        "--bmad-dir",
+        required=True,
+        help="Path to the _bmad/ directory",
+    )
+    parser.add_argument(
+        "--module-code",
+        required=True,
+        help="Module code being cleaned up (e.g. 'bmb')",
+    )
+    parser.add_argument(
+        "--also-remove",
+        action="append",
+        default=[],
+        help="Additional directory names under _bmad/ to remove (repeatable)",
+    )
+    parser.add_argument(
+        "--skills-dir",
+        help="Path to .claude/skills/ — enables safety verification that skills "
+        "are installed before removing legacy copies",
+    )
+    parser.add_argument(
+        "--verbose",
+        action="store_true",
+        help="Print detailed progress to stderr",
+    )
+    return parser.parse_args()
+
+
+def find_skill_dirs(base_path: str) -> list:
+    """Find directories that contain a SKILL.md file.
+
+    Walks the directory tree and returns the leaf directory name for each
+    directory containing a SKILL.md. These are considered skill directories.
+
+    Returns:
+        List of skill directory names (e.g. ['bmad-agent-builder', 'bmad-builder-setup'])
+    """
+    skills = []
+    root = Path(base_path)
+    if not root.exists():
+        return skills
+    for skill_md in root.rglob("SKILL.md"):
+        skills.append(skill_md.parent.name)
+    return sorted(set(skills))
+
+
+def verify_skills_installed(
+    bmad_dir: str, dirs_to_check: list, skills_dir: str, verbose: bool = False
+) -> list:
+    """Verify that skills in legacy directories exist at the installed location.
+
+    Scans each directory in dirs_to_check for skill folders (containing SKILL.md),
+    then checks that a matching directory exists under skills_dir. Directories
+    that contain no skills (like _config/) are silently skipped.
+
+    Returns:
+        List of verified skill names.
+
+    Raises SystemExit(1) if any skills are missing from skills_dir.
+    """
+    all_verified = []
+    missing = []
+
+    for dirname in dirs_to_check:
+        legacy_path = Path(bmad_dir) / dirname
+        if not legacy_path.exists():
+            continue
+
+        skill_names = find_skill_dirs(str(legacy_path))
+        if not skill_names:
+            if verbose:
+                print(
+                    f"No skills found in {dirname}/ — skipping verification",
+                    file=sys.stderr,
+                )
+            continue
+
+        for skill_name in skill_names:
+            installed_path = Path(skills_dir) / skill_name
+            if installed_path.is_dir():
+                all_verified.append(skill_name)
+                if verbose:
+                    print(
+                        f"Verified: {skill_name} exists at {installed_path}",
+                        file=sys.stderr,
+                    )
+            else:
+                missing.append(skill_name)
+                if verbose:
+                    print(
+                        f"MISSING: {skill_name} not found at {installed_path}",
+                        file=sys.stderr,
+                    )
+
+    if missing:
+        error_result = {
+            "status": "error",
+            "error": "Skills not found at installed location",
+            "missing_skills": missing,
+            "skills_dir": str(Path(skills_dir).resolve()),
+        }
+        print(json.dumps(error_result, indent=2))
+        sys.exit(1)
+
+    return sorted(set(all_verified))
+
+
+def count_files(path: Path) -> int:
+    """Count all files recursively in a directory."""
+    count = 0
+    for item in path.rglob("*"):
+        if item.is_file():
+            count += 1
+    return count
+
+
+def cleanup_directories(
+    bmad_dir: str, dirs_to_remove: list, verbose: bool = False
+) -> tuple:
+    """Remove specified directories under bmad_dir.
+
+    Returns:
+        (removed, not_found, total_files_removed) tuple
+    """
+    removed = []
+    not_found = []
+    total_files = 0
+
+    for dirname in dirs_to_remove:
+        target = Path(bmad_dir) / dirname
+        if not target.exists():
+            not_found.append(dirname)
+            if verbose:
+                print(f"Not found (skipping): {target}", file=sys.stderr)
+            continue
+
+        if not target.is_dir():
+            if verbose:
+                print(f"Not a directory (skipping): {target}", file=sys.stderr)
+            not_found.append(dirname)
+            continue
+
+        file_count = count_files(target)
+        if verbose:
+            print(
+                f"Removing {target} ({file_count} files)",
+                file=sys.stderr,
+            )
+
+        try:
+            shutil.rmtree(target)
+        except OSError as e:
+            error_result = {
+                "status": "error",
+                "error": f"Failed to remove {target}: {e}",
+                "directories_removed": removed,
+                "directories_failed": dirname,
+            }
+            print(json.dumps(error_result, indent=2))
+            sys.exit(2)
+
+        removed.append(dirname)
+        total_files += file_count
+
+    return removed, not_found, total_files
+
+
+def reject_unresolved_paths(named_paths: list[tuple[str, str]]) -> None:
+    """Exit with a clear error if any path argument still contains the literal
+    ``{project-root}`` token. That token is meaningful only inside config
+    values; filesystem path arguments must be resolved by the caller. Failing
+    loudly here prevents silently operating on a junk ``{project-root}/`` directory.
+    """
+    for name, value in named_paths:
+        if value and "{project-root}" in value:
+            print(
+                json.dumps(
+                    {
+                        "status": "error",
+                        "error": (
+                            f"Unresolved '{{project-root}}' token in {name} path: {value!r}. "
+                            "Resolve '{project-root}' to the actual project root before running "
+                            "this script — it is a filesystem path, not a config value."
+                        ),
+                    },
+                    indent=2,
+                )
+            )
+            sys.exit(1)
+
+
+def main():
+    args = parse_args()
+
+    reject_unresolved_paths(
+        [("--bmad-dir", args.bmad_dir), ("--skills-dir", args.skills_dir)]
+    )
+
+    bmad_dir = args.bmad_dir
+    module_code = args.module_code
+
+    # Build the list of directories to remove
+    dirs_to_remove = [module_code, "core"] + args.also_remove
+    # Deduplicate while preserving order
+    seen = set()
+    unique_dirs = []
+    for d in dirs_to_remove:
+        if d not in seen:
+            seen.add(d)
+            unique_dirs.append(d)
+    dirs_to_remove = unique_dirs
+
+    if args.verbose:
+        print(f"Directories to remove: {dirs_to_remove}", file=sys.stderr)
+
+    # Safety check: verify skills are installed before removing
+    verified_skills = None
+    if args.skills_dir:
+        if args.verbose:
+            print(
+                f"Verifying skills installed at {args.skills_dir}",
+                file=sys.stderr,
+            )
+        verified_skills = verify_skills_installed(
+            bmad_dir, dirs_to_remove, args.skills_dir, args.verbose
+        )
+
+    # Remove directories
+    removed, not_found, total_files = cleanup_directories(
+        bmad_dir, dirs_to_remove, args.verbose
+    )
+
+    # Build result
+    result = {
+        "status": "success",
+        "bmad_dir": str(Path(bmad_dir).resolve()),
+        "directories_removed": removed,
+        "directories_not_found": not_found,
+        "files_removed_count": total_files,
+    }
+
+    if args.skills_dir:
+        result["safety_checks"] = {
+            "skills_verified": True,
+            "skills_dir": str(Path(args.skills_dir).resolve()),
+            "verified_skills": verified_skills,
+        }
+    else:
+        result["safety_checks"] = None
+
+    print(json.dumps(result, indent=2))
+
+
+if __name__ == "__main__":
+    main()