src/workflows/3-technical/gds-create-epics-and-stories/SKILL.md (1)

6-26: ⚠️ Potential issue | 🟡 Minor

Clarify the working directory for script execution.

Same working directory ambiguity as other workflow SKILL.md files.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/workflows/3-technical/gds-create-epics-and-stories/SKILL.md` around lines
6 - 26, The SKILL.md is ambiguous about which working directory to run scripts
like scripts/resolve-customization.py from; update the document (references:
scripts/resolve-customization.py, commands shown using python3) to explicitly
state the working directory (e.g., “run from repository root”) and clarify
whether paths like ./workflow.md and listed resource files are relative to that
root or to the workflow folder, and add a single example command showing the
full relative invocation from the specified directory to remove ambiguity.

src/workflows/3-technical/gds-check-implementation-readiness/SKILL.md (1)

6-26: ⚠️ Potential issue | 🟡 Minor

Clarify the working directory for script execution.

Same working directory ambiguity as other workflow SKILL.md files.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/workflows/3-technical/gds-check-implementation-readiness/SKILL.md` around
lines 6 - 26, The instructions in SKILL.md are ambiguous about where to run
scripts; update the SKILL.md content to explicitly state the working directory
and how to execute the script: specify that scripts/resolve-customization.py
should be invoked from the repository root (or indicate if it must be run from
the scripts/ directory), and clarify whether paths in --key values (inject,
additional_resources, inject.after) and references in ./workflow.md are relative
to that root or another directory; mention the expected cwd for reading files
listed in additional_resources and for resolving inject.before/after so users
know where to run the python command and where file paths are resolved.

src/workflows/2-design/gds-create-narrative/SKILL.md (1)

6-26: ⚠️ Potential issue | 🟡 Minor

Clarify the working directory for script execution.

Same working directory ambiguity as other workflow SKILL.md files.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/workflows/2-design/gds-create-narrative/SKILL.md` around lines 6 - 26,
The instructions are ambiguous about the working directory when running scripts;
clarify where to run scripts/resolve-customization.py (e.g., from repo root) and
how file paths in additional_resources are resolved. Update SKILL.md to state:
run commands from the repository root (or specify alternative), that paths in
additional_resources are relative to that working directory (or absolute), and
ensure references to ./workflow.md are resolved from the same base directory;
mention the exact command examples used (python3
scripts/resolve-customization.py gds-create-narrative --key inject --key
additional_resources and python3 scripts/resolve-customization.py
gds-create-narrative --key inject.after) so readers know the expected CWD and
path resolution for inject.before, additional_resources, and inject.after.

src/workflows/3-technical/gds-generate-project-context/SKILL.md (1)

6-26: ⚠️ Potential issue | 🟡 Minor

Clarify the working directory for script execution.

Same issue as in gds-game-architecture/SKILL.md: the working directory for running scripts/resolve-customization.py is not specified, which may confuse users.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/workflows/3-technical/gds-generate-project-context/SKILL.md` around lines
6 - 26, The instructions omit the working directory for running
scripts/resolve-customization.py; update the documentation around the two
command invocations (the Resolve Customization command that calls "python3
scripts/resolve-customization.py gds-generate-project-context --key inject --key
additional_resources" and the Post-Workflow command that calls "python3
scripts/resolve-customization.py gds-generate-project-context --key
inject.after") to explicitly state they must be executed from the repository
root (or specify the exact working directory used by your workflows), and add a
short note telling users how to run the command from a different cwd (e.g.,
prepend the repo root path or cd into repo root) so the script path resolves
correctly.

src/workflows/4-production/gds-retrospective/SKILL.md (1)

6-26: ⚠️ Potential issue | 🟡 Minor

Clarify the working directory for script execution.

Same working directory ambiguity as other workflow SKILL.md files.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/workflows/4-production/gds-retrospective/SKILL.md` around lines 6 - 26,
Clarify the working directory for the resolve-customization commands by stating
where to run scripts/resolve-customization.py (e.g., "run from the repository
root" or "run from the scripts/ directory") and update the three Run lines that
reference "python3 scripts/resolve-customization.py gds-retrospective ..." so
they explicitly specify the required working directory or use an explicit path
(e.g., "./scripts/resolve-customization.py" vs "scripts/...") and add a short
note in the "Available Scripts" or "Resolve Customization" and "Post-Workflow
Customization" sections indicating the expected CWD and any environment
assumptions; ensure references to the script name
scripts/resolve-customization.py and keys (--key inject, --key
additional_resources, --key inject.after) are preserved.

src/workflows/gametest/gds-test-automate/SKILL.md (1)

6-26: ⚠️ Potential issue | 🟡 Minor

Clarify the working directory for script execution.

Same working directory ambiguity issue as noted in other SKILL.md files.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/workflows/gametest/gds-test-automate/SKILL.md` around lines 6 - 26,
Clarify which working directory to use when running the resolve-customization
script: state explicitly that the commands (e.g., python3
scripts/resolve-customization.py gds-test-automate --key inject --key
additional_resources and python3 scripts/resolve-customization.py
gds-test-automate --key inject.after) must be executed from the repository root
(or specify an alternative directory such as the scripts directory) and show the
exact shell steps to ensure correctness (e.g., cd to repo root || cd scripts) so
readers know where relative paths resolve and which directory contains
scripts/resolve-customization.py.

src/workflows/gds-quick-flow/gds-quick-dev-new-preview/SKILL.md-16-17 (1)

16-17: ⚠️ Potential issue | 🟡 Minor

Document the base path for additional_resources.

These instructions say to read each listed file, but they don't repeat that the paths are relative to {project-root}. Without that, callers can resolve them from the wrong directory and miss the intended resources.

Suggested fix

-If `additional_resources` is not empty, read each listed file and incorporate as reference context.
+If `additional_resources` is not empty, read each listed file relative to `{project-root}` and incorporate its contents as reference context.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/workflows/gds-quick-flow/gds-quick-dev-new-preview/SKILL.md` around lines
16 - 17, Update the SKILL.md text around the handling of inject.before and
additional_resources to explicitly state that file paths in additional_resources
are resolved relative to the project root (i.e., `{project-root}`); mention that
the system will read each listed file from `{project-root}` and incorporate its
contents as reference context, and clarify that inject.before content is treated
as higher-priority context so callers should provide relative paths from
`{project-root}` when listing additional_resources.

src/workflows/3-technical/gds-game-architecture/SKILL.md-6-26 (1)

6-26: ⚠️ Potential issue | 🟡 Minor

Clarify the working directory for script execution.

The documentation instructs users to run python3 scripts/resolve-customization.py but doesn't specify the working directory. Users may be unclear whether to execute the script from the skill's directory (e.g., src/workflows/3-technical/gds-game-architecture/), the project root, or elsewhere.

Consider adding a brief note indicating the expected working directory, such as:

Run from the skill directory:
`python3 scripts/resolve-customization.py gds-game-architecture --key inject --key additional_resources`

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/workflows/3-technical/gds-game-architecture/SKILL.md` around lines 6 -
26, The docs lack the working-directory context for running
scripts/resolve-customization.py; update SKILL.md to state where to run the
commands (e.g., run from the repository root or the skill directory) and give
explicit examples for the three commands referencing
scripts/resolve-customization.py and the skill key gds-game-architecture, and
mention that resolved keys inject, additional_resources and inject.after are
produced as JSON to be consumed by the workflow referenced in ./workflow.md so
users know whether to run the command from the skill directory
(src/workflows/3-technical/gds-game-architecture/) or the project root.

src/agents/gds-agent-game-qa/SKILL.md-44-45 (1)

44-45: ⚠️ Potential issue | 🟡 Minor

Make project-context.md resolution deterministic.

Line 44's **/project-context.md search can match multiple files in a monorepo, but the activation flow never says which one wins. Please define a stable rule, e.g. nearest to the current working directory, so the agent does not load different standards depending on search order.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/agents/gds-agent-game-qa/SKILL.md` around lines 44 - 45, The glob
"**/project-context.md" in the "Load project context" step is ambiguous in
monorepos; change the resolution to be deterministic by: search for all matches
to "**/project-context.md", then select the single file nearest to the current
working directory (fewest directory levels from CWD); if there is a tie, break
ties deterministically (e.g., choose the lexicographically smallest path or
prefer workspace root), update the "Load project context" step and any
implementation that performs the search to apply this selection logic, and
document the deterministic rule in SKILL.md.

src/agents/gds-agent-game-dev/scripts/resolve-customization.py-91-96 (1)

91-96: ⚠️ Potential issue | 🟡 Minor

Restrict merge-by-code to the menu field.

Lines 93-94 currently apply menu semantics to any list of dicts that happens to contain a code key, even though the documented rule is [[menu]] only. A future non-menu array with code entries would merge unexpectedly instead of replacing atomically.

Suggested fix

-        elif _is_menu_array(over_val) and _is_menu_array(base_val):
+        elif key == "menu" and _is_menu_array(over_val) and _is_menu_array(base_val):
             merged[key] = merge_menu(base_val, over_val)

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/agents/gds-agent-game-dev/scripts/resolve-customization.py` around lines
91 - 96, The current merge treats any list-of-dicts with a "code" key as a menu
by using _is_menu_array, causing unintended merges; modify the conditional in
deep_merge so merge_menu is only used when the current key is exactly "menu"
(i.e., change the elif to require key == "menu" && _is_menu_array(over_val) &&
_is_menu_array(base_val)), otherwise fall back to replacing with over_val;
update references to deep_merge, _is_menu_array, merge_menu, over_val, base_val,
and merged to implement this restriction.

src/workflows/gametest/gds-playtest-plan/scripts/resolve-customization.py (1)

168-174: Warn on unresolved --key requests instead of silently dropping them.

Silent omission makes typos in dotted keys hard to detect during workflow wiring.

🛠️ Suggested improvement

     if args.keys:
         result = {}
         for key in args.keys:
             value = extract_key(merged, key)
-            if value is not None:
-                result[key] = value
+            if value is None:
+                print(f"warning: unresolved key '{key}'", file=sys.stderr)
+                continue
+            result[key] = value
         json.dump(result, sys.stdout, indent=2, ensure_ascii=False)

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/workflows/gametest/gds-playtest-plan/scripts/resolve-customization.py`
around lines 168 - 174, The current loop over args.keys silently drops keys when
extract_key(merged, key) returns None; change it to emit a warning for each
unresolved key so typos are visible. In the block that iterates over args.keys
(and uses extract_key and merged to build result), when value is None write a
warning to stderr or via logging that includes the requested key name and
context (e.g., "unresolved key: <key>") instead of silently skipping it; still
add found keys to result and keep the existing json.dump behavior.

src/workflows/4-production/gds-dev-story/scripts/resolve-customization.py (2)

67-75: Menu item ordering may vary.

merge_menu builds results using a dict keyed by code. While Python 3.7+ preserves insertion order, the final order will be: base items (in their original order, minus any replaced by override), then new override items appended. If strict ordering is required for menus, this may need adjustment.

If menu order matters, consider preserving original base order and appending only genuinely new items:

♻️ Order-preserving alternative

 def merge_menu(base: list[dict], override: list[dict]) -> list[dict]:
     """Merge-by-code: matching codes replace; new codes append."""
-    result_by_code: dict[str, dict] = {item["code"]: dict(item) for item in base if "code" in item}
+    override_by_code = {item["code"]: dict(item) for item in override if "code" in item}
+    result = []
+    seen_codes = set()
+    # Preserve base order, replacing with overrides where matched
+    for item in base:
+        if "code" not in item:
+            continue
+        code = item["code"]
+        seen_codes.add(code)
+        result.append(override_by_code.get(code, dict(item)))
+    # Append new items from override
     for item in override:
         if "code" not in item:
             print(f"warning: menu item missing 'code' key, skipping: {item}", file=sys.stderr)
             continue
-        result_by_code[item["code"]] = dict(item)
-    return list(result_by_code.values())
+        if item["code"] not in seen_codes:
+            result.append(dict(item))
+    return result

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/workflows/4-production/gds-dev-story/scripts/resolve-customization.py`
around lines 67 - 75, merge_menu currently collects items into result_by_code
which yields base items (with replacements) followed by override-only items in
arbitrary dict value order; to preserve menu ordering change the algorithm in
merge_menu to iterate base in order and for each base item yield the override
item if override contains the same "code" (replace in-place), otherwise yield
the base item, then iterate override in order and append only items whose "code"
is not present in the base (new items), using the same "code" checks and stderr
warnings for missing codes; reference merge_menu and result_by_code to locate
where to implement this ordering-preserving merge.

---

1-183: Implementation is solid; consider consolidating duplicated scripts.

The three-layer merge logic is well-implemented with appropriate error handling. However, this script is duplicated across 35 skill directories. If a bug is found or an enhancement is needed, all copies must be updated.

Consider consolidating into a single shared script that can be invoked with the skill directory as an argument, or symlinked from each skill's scripts/ directory. This would reduce maintenance burden while preserving the per-skill invocation pattern.

Example approach:

# Single shared script at:
# _bmad/scripts/resolve-customization.py

# Per-skill invocation:
python3 _bmad/scripts/resolve-customization.py --skill-dir src/workflows/4-production/gds-dev-story gds-dev-story

Alternatively, if the current approach is intentional for self-contained skill packaging, that's a valid trade-off—just document the update process when changes are needed.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/workflows/4-production/gds-dev-story/scripts/resolve-customization.py`
around lines 1 - 183, The repo has 35 copies of this script—consolidate into a
single shared script and update per-skill invocations to call it (or symlink it)
to avoid duplicate maintenance. Extract the core functions (find_project_root,
load_toml, _is_menu_array, merge_menu, deep_merge, extract_key) and the CLI flow
around defaults_path/project_root into one shared
_bmad/scripts/resolve-customization.py, change the entrypoint to accept either
--skill-dir (path to skill containing customize.toml) and skill_name (for
looking up project overrides) or preserve the existing positional skill_name but
compute defaults_path from --skill-dir; keep the same JSON output behavior and
flags (args.keys), and update each skill's scripts/resolve-customization.py to
become a tiny shim that calls the shared script (or create a symlink) so
invocation and behavior remain identical.

src/workflows/2-design/gds-create-ux-design/scripts/resolve-customization.py (1)

1-183: Consider centralizing resolver logic instead of copying per-skill scripts.

This implementation is duplicated across many skills; a shared resolver module/script would reduce drift and make bug fixes (like merge edge cases) one-and-done.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/workflows/2-design/gds-create-ux-design/scripts/resolve-customization.py`
around lines 1 - 183, This repo has duplicate per-skill resolver scripts;
extract the core logic (load_toml, find_project_root, deep_merge, merge_menu,
_is_menu_array, extract_key, and the main merge flow used in main) into a single
shared module (e.g., bmad.resolve_customization) that exposes a function like
resolve_customization(skill_name: str, start_dir: Path) -> dict and an optional
resolve_keys(data, keys) helper; update each per-skill script to import and call
that function (keeping only CLI thin-wrapper code), remove duplicated functions
from skill scripts, and add unit tests covering merge_menu, deep_merge, and
dotted-key extraction to prevent future drift. Ensure public API preserves
behavior (defaults <- team <- user, menu merge-by-code, arrays atomic replace,
and CLI --key handling) and update any scripts to use the new module's JSON
output logic.

src/workflows/3-technical/gds-create-epics-and-stories/scripts/resolve-customization.py (1)

30-183: Extract this resolver into one shared implementation.

This file is effectively the same as the other scripts/resolve-customization.py copies in the PR. Every behavior change now needs dozens of manual edits, which makes drift likely the next time merge logic changes.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In
`@src/workflows/3-technical/gds-create-epics-and-stories/scripts/resolve-customization.py`
around lines 30 - 183, This file duplicates resolver logic across the repo;
extract the shared implementation so other copies import it instead of drifting.
Move the core functions (find_project_root, load_toml, _is_menu_array,
merge_menu, deep_merge, extract_key and the merge/load logic) into a single
shared module (e.g. resolve_customization/shared or bmad.resolve_customization)
exposing a resolve_customizations(skill_name, keys=None, cwd=None) or a
main_entry function, then change this script's main to be a thin CLI wrapper
that imports and calls that shared function (keeping argument parsing here).
Update other scripts to import the same shared module and remove duplicate
function bodies from their files.

src/workflows/1-preproduction/gds-brainstorm-game/scripts/resolve-customization.py (1)

1-183: Consider centralizing the resolver instead of copying it into every skill.

This file is effectively the same implementation being added in many places. Any future merge bug or security fix now needs to be patched across every copy, which is easy to miss.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In
`@src/workflows/1-preproduction/gds-brainstorm-game/scripts/resolve-customization.py`
around lines 1 - 183, This script duplicates a resolver used across many skills;
extract the common logic (find_project_root, load_toml, _is_menu_array,
merge_menu, deep_merge, extract_key and the TOML merge/output behavior) into a
single shared module (e.g., bmad.customization.resolver) and replace per-skill
copies with a small wrapper that imports the shared resolver and invokes a
single function/CLI entrypoint (e.g., resolve_customization(skill_name,
keys=None) or main()) so fixes apply centrally; ensure the shared resolver still
computes defaults_path relative to the caller's skill directory (accepting an
optional skill_dir or defaults_path argument) and update the script to only
parse CLI args and call the shared API.

src/agents/gds-agent-game-designer/customize.toml (1)

47-50: Remove or complete the empty “Menu customization docs” section.

Line 48 introduces a menu customization section, but no menu defaults or guidance follow. This creates avoidable ambiguity for users editing overrides.

Minimal cleanup option

-# ──────────────────────────────────────────────────────────────────
-# Menu customization docs
-# ──────────────────────────────────────────────────────────────────
-
 # ──────────────────────────────────────────────────────────────────
 # Injected prompts
 # ──────────────────────────────────────────────────────────────────

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/agents/gds-agent-game-designer/customize.toml` around lines 47 - 50, The
"# Menu customization docs" placeholder is empty and should be removed or
completed: either delete that header and any blank lines to avoid confusion, or
replace it with a short, concrete guidance block that documents the expected
menu override keys (e.g., items, order, labels) and the default values/behavior
used by this agent; update the section where "# Menu customization docs" appears
to include one or two brief examples and a note about precedence so users know
how to write overrides.

src/workflows/4-production/gds-sprint-planning/SKILL.md (1)

10-25: Clarify command execution directory.

Please explicitly state these commands are run from the src/workflows/4-production/gds-sprint-planning/ directory to avoid path-resolution mistakes.

Suggested docs tweak

 ## Resolve Customization
 
 Resolve `inject` and `additional_resources` from customization:
-Run: `python3 scripts/resolve-customization.py gds-sprint-planning --key inject --key additional_resources`
+Run from `src/workflows/4-production/gds-sprint-planning/`:
+`python3 scripts/resolve-customization.py gds-sprint-planning --key inject --key additional_resources`
 Use the JSON output as resolved values.
@@
 After the workflow completes, resolve `inject.after` from customization:
-Run: `python3 scripts/resolve-customization.py gds-sprint-planning --key inject.after`
+Run from `src/workflows/4-production/gds-sprint-planning/`:
+`python3 scripts/resolve-customization.py gds-sprint-planning --key inject.after`

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/workflows/4-production/gds-sprint-planning/SKILL.md` around lines 10 -
25, The document lacks an explicit working-directory for the resolve commands;
update SKILL.md (the "Resolve Customization" and "Post-Workflow Customization"
sections) to state that the following commands must be executed from the
src/workflows/4-production/gds-sprint-planning/ directory, and clarify that the
scripts referenced (resolve-customization.py) are relative to that directory
when resolving keys inject, additional_resources, inject.before and inject.after
and when reading files referenced by additional_resources; ensure the note also
points to ./workflow.md for subsequent steps so readers know the expected cwd
for all referenced paths.

src/agents/gds-agent-game-architect/customize.toml (1)

47-49: Consider removing the empty placeholder section.

The "Menu customization docs" section header with no content appears to be leftover scaffolding. If there's no immediate plan to document menu customization here, consider removing these lines to keep the file clean.

🧹 Proposed cleanup

-# ──────────────────────────────────────────────────────────────────
-# Menu customization docs
-# ──────────────────────────────────────────────────────────────────
-

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/agents/gds-agent-game-architect/customize.toml` around lines 47 - 49,
Remove the empty placeholder section containing the "Menu customization docs"
header and its surrounding separator comment blocks (the three-comment separator
lines and the "Menu customization docs" line) so the TOML file no longer
contains unused scaffolding; if you plan to add content later, add it as a real
subsection instead of leaving blank headers.

src/agents/gds-agent-game-scrum-master/SKILL.md (1)

43-56: Avoid a second source of truth for the capabilities menu.

Step 1 resolves menu from customization, but Line 43 still starts from a hardcoded table. That means default capabilities now live in both customize.toml and SKILL.md, so they can drift. Prefer presenting the resolved menu directly, or clearly treat the markdown table as generated from the TOML defaults.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/agents/gds-agent-game-scrum-master/SKILL.md` around lines 43 - 56, The
hardcoded capabilities table in SKILL.md duplicates defaults stored in
customize.toml causing a second source of truth; update SKILL.md to instead
present the resolved `menu` (the merged result used at runtime) or clearly
indicate the table is generated from TOML defaults. Specifically, replace the
static table block (the table under "Capabilities") with a dynamic
representation or a statement that prints/embeds the resolved `menu`, and ensure
the documentation references the `menu` resolution logic (the same `menu`
variable/process used when merging customization) so only the resolved `menu` is
shown to users.

src/workflows/gds-quick-flow/gds-quick-dev/scripts/resolve-customization.py (1)

1-183: Please centralize the resolver implementation.

This file is one of many near-identical copies of the same resolver. The recent menu fixes already had to be replayed across every copy, so future hardening will have the same fan-out cost. A shared module or single repo-level script would make follow-up fixes much safer.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/workflows/gds-quick-flow/gds-quick-dev/scripts/resolve-customization.py`
around lines 1 - 183, This resolver is a near-duplicate of many copies;
centralize it into a single shared module (e.g., expose a resolver function) and
have this script become a thin CLI wrapper that imports and calls that shared
implementation: extract the functions find_project_root, load_toml,
_is_menu_array, merge_menu, deep_merge, extract_key and the merging logic into a
repo-level module (e.g., bmad.customization.resolve or similar) with a clear API
like resolve_customization(skill_name: str, start_path: Path | None) -> dict,
and modify this file to import that API and only handle CLI args, path-to-skill
resolution and JSON printing; preserve behavior for defaults_path resolution
(allow passing skill_dir or defaults_path into the shared API) and keep
warnings/IO behavior consistent so other scripts can reuse fixes (menu merging
etc.) without duplicated code.

src/agents/gds-agent-game-dev/scripts/resolve-customization.py (1)

1-183: Move the resolver into shared code instead of copying it per skill.

This PR adds the same resolver implementation to many directories. Any future fix to merge semantics, path resolution, or error handling now needs the same edit everywhere.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/agents/gds-agent-game-dev/scripts/resolve-customization.py` around lines
1 - 183, This file duplicates resolver logic across skills; extract the shared
logic (find_project_root, load_toml, _is_menu_array, merge_menu, deep_merge,
extract_key and the merge/load behavior) into a single shared module (e.g., a
package module like bmad.customization or bmad_tools.customize) and export a
simple API function (e.g., resolve_customization(skill_name, start_path=... ,
keys=None) or resolve_and_dump(args)) that the per-skill script can call; then
replace each copied resolve-customization.py with a tiny wrapper that imports
the shared function and handles CLI arg parsing (or have the shared module parse
args) so fixes to merge semantics, path resolution, or error handling are
changed once in the shared module rather than in every duplicate file.

src/agents/gds-agent-game-qa/scripts/resolve-customization.py-129-132 (1)

129-132: ⚠️ Potential issue | 🟡 Minor

Validate skill_name to prevent path traversal outside customizations directory.

At Lines 160-161, args.skill_name is interpolated directly into a filename. Inputs like ../../x can escape _bmad/customizations and read unintended files.

Proposed fix

 import argparse
 import json
+import re
 import sys
 import tomllib
@@
     args = parser.parse_args()
+    if not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._-]*", args.skill_name):
+        parser.error("skill_name must match [A-Za-z0-9][A-Za-z0-9._-]*")

Also applies to: 140-141, 159-161

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/agents/gds-agent-game-qa/scripts/resolve-customization.py` around lines
129 - 132, Inputs in parser.add_argument are used verbatim (args.skill_name) to
build filenames under the _bmad/customizations directory, allowing path
traversal (e.g. ../../). Validate and sanitize args.skill_name before using it:
reject any value containing path separators or suspicious sequences and enforce
a strict whitelist pattern (e.g. ^[A-Za-z0-9_-]+$), or map skill names to known
allowed entries; when building the file path use pathlib.Path to join and
resolve (Path(custom_dir) / args.skill_name).resolve() and ensure the resolved
path is a child of the customizations directory (compare
.resolve().is_relative_to(custom_dir.resolve()) or check prefix), and apply this
validation wherever args.skill_name is interpolated into filenames (references:
parser.add_argument, args.skill_name, the _bmad/customizations file operations).

src/agents/gds-agent-game-solo-dev/scripts/resolve-customization.py-148-152 (1)

148-152: ⚠️ Potential issue | 🟡 Minor

Prefer skill-local root when CWD root is not a BMAD project.

Line 148 trusts the current working directory first. If this script is launched from another git repo, customization files for this skill can be silently missed.

Suggested fix

-    project_root = find_project_root(Path.cwd())
-    if project_root is None:
-        # Try from the skill directory as fallback
-        project_root = find_project_root(skill_dir)
+    project_root = find_project_root(Path.cwd())
+    if project_root is None or not (project_root / "_bmad" / "customizations").is_dir():
+        # Fall back to the script's repository when CWD is outside a BMAD project
+        project_root = find_project_root(skill_dir)

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/agents/gds-agent-game-solo-dev/scripts/resolve-customization.py` around
lines 148 - 152, The current lookup prefers find_project_root(Path.cwd()) which
can pick up a different repo and miss this skill's customization; change the
resolution to prefer the skill-local root first by calling
find_project_root(skill_dir) and using that if present, then fall back to
find_project_root(Path.cwd()); update the project_root assignment and any
downstream logic that uses project_root (references: find_project_root,
project_root, Path.cwd(), skill_dir) so the skill's local BMAD project is
selected when available.

src/workflows/4-production/gds-sprint-status/scripts/resolve-customization.py (1)

42-51: Add a strict mode for TOML load failures.

Returning {} on parse/read errors can silently mask broken customization. A --strict flag (non-zero exit on failure) would improve CI safety while keeping current behavior as default.

🧪 Proposed direction

-def load_toml(path: Path) -> dict[str, Any]:
+def load_toml(path: Path, *, strict: bool = False) -> dict[str, Any]:
@@
-    except (tomllib.TOMLDecodeError, OSError) as exc:
+    except (tomllib.TOMLDecodeError, OSError) as exc:
+        if strict:
+            raise
         print(f"warning: failed to parse {path}: {exc}", file=sys.stderr)
         return {}

# in argparse
parser.add_argument("--strict", action="store_true", help="Fail on TOML parse/read errors.")
# and pass strict=args.strict to each load_toml(...) call

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In
`@src/workflows/4-production/gds-sprint-status/scripts/resolve-customization.py`
around lines 42 - 51, Introduce a --strict mode that makes TOML load failures
fatal: add parser.add_argument("--strict", action="store_true", help="Fail on
TOML parse/read errors.") and thread the resulting flag into each load_toml(...)
call, then modify load_toml(path: Path, strict: bool = False) to keep current
behavior (return {}) on non-strict errors but, when strict is True, log the
error and exit non-zero (sys.exit(1)) or re-raise the exception instead of
returning {}; update all call sites to pass strict=args.strict.

src/agents/gds-agent-game-designer/scripts/resolve-customization.py (1)

149-152: Emit a warning when project root is unresolved.

If both root lookups fail, overrides are skipped silently. Adding a warning to stderr would make misconfigured invocation context easier to diagnose.

🧭 Suggested diagnostic

@@
     project_root = find_project_root(Path.cwd())
     if project_root is None:
         # Try from the skill directory as fallback
         project_root = find_project_root(skill_dir)
+    if project_root is None:
+        print(
+            "warning: project root not found; using skill defaults only (team/user overrides skipped)",
+            file=sys.stderr,
+        )

Also applies to: 158-162

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/agents/gds-agent-game-designer/scripts/resolve-customization.py` around
lines 149 - 152, The code currently falls back to project_root =
find_project_root(skill_dir) and silently skips overrides if project_root
remains None; update the logic in resolve-customization.py so that after both
lookups (the initial project_root check and the fallback using
find_project_root(skill_dir)) you detect when project_root is still None and
emit a clear warning to stderr (e.g., using sys.stderr.write or logging.warning)
indicating that project root could not be resolved and overrides will be
skipped; reference the project_root variable, the find_project_root call, and
the overrides handling branch so the warning is emitted in both the block at the
existing fallback (project_root = find_project_root(skill_dir)) and the similar
block around lines 158-162.

src/workflows/gds-quick-flow/gds-quick-dev/scripts/resolve-customization.py (1)

67-75: Preserve base menu fields when overriding by code.

Line 74 fully replaces matching menu items. If an override item is partial, default fields are dropped. Prefer deep-merging matching items by code.

Proposed refactor

 def merge_menu(base: list[dict], override: list[dict]) -> list[dict]:
     """Merge-by-code: matching codes replace; new codes append."""
     result_by_code: dict[str, dict] = {item["code"]: dict(item) for item in base if "code" in item}
     for item in override:
         if "code" not in item:
             print(f"warning: menu item missing 'code' key, skipping: {item}", file=sys.stderr)
             continue
-        result_by_code[item["code"]] = dict(item)
+        code = item["code"]
+        if code in result_by_code:
+            result_by_code[code] = deep_merge(result_by_code[code], dict(item))
+        else:
+            result_by_code[code] = dict(item)
     return list(result_by_code.values())

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/workflows/gds-quick-flow/gds-quick-dev/scripts/resolve-customization.py`
around lines 67 - 75, The merge_menu function currently replaces a base item
entirely when an override with the same "code" exists; change it to deep-merge
matching items so base fields are preserved when overrides are partial: in
merge_menu, when building result_by_code for base use the existing
{item["code"]: dict(item)} approach, but when processing override items (in the
for item in override loop) detect existing result_by_code[item["code"]] and
perform a recursive/deep merge of dict values (and lists if needed) rather than
assigning dict(item) directly; implement a helper like deep_merge_dicts(a: dict,
b: dict) and call result_by_code[item["code"]] =
deep_merge_dicts(result_by_code[item["code"]], dict(item)) so only provided
override keys replace base keys and nested structures are merged.

src/workflows/4-production/gds-code-review/scripts/resolve-customization.py (1)

148-152: Prefer resolving project root from the script location first.

Using Path.cwd() first at Line [148] can bind to an unrelated repo when the script is invoked from outside this project. Resolve from skill_dir first, then optionally fall back to cwd.

♻️ Proposed change

-    project_root = find_project_root(Path.cwd())
-    if project_root is None:
-        # Try from the skill directory as fallback
-        project_root = find_project_root(skill_dir)
+    # Prefer script-local discovery to avoid picking an unrelated cwd repository.
+    project_root = find_project_root(skill_dir)
+    if project_root is None:
+        project_root = find_project_root(Path.cwd())

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/workflows/4-production/gds-code-review/scripts/resolve-customization.py`
around lines 148 - 152, The code currently resolves project_root by calling
find_project_root(Path.cwd()) first which can pick up an unrelated repo; change
the order so you call find_project_root(skill_dir) first and assign to
project_root, and only if that returns None call find_project_root(Path.cwd())
as a fallback; update the variables around project_root, find_project_root,
Path.cwd(), and skill_dir accordingly so the script prefers the script's
directory before the current working directory.

src/workflows/1-preproduction/gds-brainstorm-game/scripts/resolve-customization.py (1)

148-152: Prefer skill_dir as the primary root-discovery anchor.

Current order is cwd-first, so running from an unrelated git repo can resolve the wrong root and miss intended _bmad/customizations.

🔧 Proposed refactor

-    project_root = find_project_root(Path.cwd())
-    if project_root is None:
-        # Try from the skill directory as fallback
-        project_root = find_project_root(skill_dir)
+    project_root = find_project_root(skill_dir)
+    if project_root is None:
+        # Fallback for ad-hoc execution from outside the repo tree
+        project_root = find_project_root(Path.cwd())

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In
`@src/workflows/1-preproduction/gds-brainstorm-game/scripts/resolve-customization.py`
around lines 148 - 152, The root discovery currently calls
find_project_root(Path.cwd()) first which can pick up an unrelated repo; change
the lookup order to call find_project_root(skill_dir) as the primary anchor and
only call find_project_root(Path.cwd()) as the fallback if that returns None,
updating the surrounding logic/comments accordingly; target the project_root
variable and the two find_project_root calls (using skill_dir and Path.cwd()) to
implement this swap.

src/workflows/3-technical/gds-generate-project-context/scripts/resolve-customization.py (1)

130-132: Fail fast when skill_name does not match this resolver’s skill directory.

Line 145 always loads defaults from this script’s parent skill, but Line 130-Line 132 accepts any skill_name. A typo can silently merge the wrong override file into the right defaults. Add a strict equality check to avoid hard-to-trace config drift.

✅ Proposed guard

     args = parser.parse_args()
+    expected_skill = skill_dir.name
+    if args.skill_name != expected_skill:
+        parser.error(f"skill_name must be '{expected_skill}' for this resolver")

Also applies to: 143-145

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In
`@src/workflows/3-technical/gds-generate-project-context/scripts/resolve-customization.py`
around lines 130 - 132, Add a strict equality guard to reject mismatched skill
names so that the CLI arg "skill_name" must equal this resolver's parent skill
directory before loading defaults; specifically, in the code that parses the
"skill_name" argument and before the block that loads defaults from this
script’s parent skill, compare the provided skill_name to the resolver’s own
skill id (derived from the parent directory or existing constant) and raise/exit
with an error if they differ to prevent silent merging of wrong override files.

src/agents/gds-agent-tech-writer/scripts/resolve-customization.py (1)

130-132: Validate skill_name against the resolver’s owning skill directory.

Line 130 and Line 160 allow accidental cross-skill merges (defaults from this skill + overrides from another skill name). Add a mismatch guard to prevent silently producing inconsistent configs.

💡 Proposed fix

@@
-    args = parser.parse_args()
-
     # Locate the skill's own customize.toml (one level up from scripts/)
     script_dir = Path(__file__).resolve().parent
     skill_dir = script_dir.parent
     defaults_path = skill_dir / "customize.toml"
+    args = parser.parse_args()
+    if args.skill_name != skill_dir.name:
+        parser.error(
+            f"skill_name '{args.skill_name}' does not match resolver skill '{skill_dir.name}'"
+        )

Also applies to: 160-161

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/agents/gds-agent-tech-writer/scripts/resolve-customization.py` around
lines 130 - 132, The CLI accepts a skill_name argument but does not guard
against mixing defaults from the resolver's owning skill directory with
overrides from a different skill; add a validation step that compares the parsed
skill_name argument to the resolver's owning skill identifier (e.g., the
resolver's skill_dir or owning_skill variable) and aborts with a clear error if
they differ to prevent cross-skill merges. Insert this check immediately after
parsing args (where "skill_name" is read) and also before applying
overrides/merging configs (the code path that combines defaults and overrides)
so both code paths reject mismatched skill names. Ensure the error returns
non-zero/raises SystemExit with a descriptive message mentioning both names.

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes

src/workflows/2-design/gds-create-gdd/scripts/resolve-customization.py (1)

130-132: ⚠️ Potential issue | 🔴 Critical

Block path traversal by validating skill_name before building file paths.

args.skill_name is used unsafely in path construction at Line 160 and Line 161. Inputs containing path separators can escape _bmad/customizations and read arbitrary files.

🔒 Proposed fix

@@
 import argparse
 import json
+import re
 import sys
 import tomllib
 from pathlib import Path
 from typing import Any
@@
     args = parser.parse_args()
+    if not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._-]*", args.skill_name):
+        parser.error("skill_name may only contain letters, digits, '.', '_' or '-'")
@@
     if project_root is not None:
         customizations_dir = project_root / "_bmad" / "customizations"
         team = load_toml(customizations_dir / f"{args.skill_name}.toml")
         user = load_toml(customizations_dir / f"{args.skill_name}.user.toml")

Also applies to: 159-161

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/workflows/2-design/gds-create-gdd/scripts/resolve-customization.py`
around lines 130 - 132, Validate and sanitize args.skill_name before using it to
build file paths in resolve-customization.py: enforce an allowlist (e.g., only
lowercase letters, digits, hyphen, underscore) or reject inputs containing path
separators or suspicious characters, then use the validated value when
constructing paths (instead of the raw args.skill_name); additionally, after
joining with the base "_bmad/customizations", call os.path.normpath and verify
the resulting path starts with the intended base directory, raising an error if
validation fails. Use the identifiers args.skill_name and the path-building code
that joins "_bmad/customizations" to locate where to apply these checks.

src/workflows/3-technical/gds-game-architecture/scripts/resolve-customization.py (3)

148-151: ⚠️ Potential issue | 🟠 Major

Resolve project root from skill_dir before Path.cwd().

At Line 148-Line 151, probing Path.cwd() first can select the wrong repository when invoked from another working directory.

Suggested fix

-    project_root = find_project_root(Path.cwd())
-    if project_root is None:
-        # Try from the skill directory as fallback
-        project_root = find_project_root(skill_dir)
+    project_root = find_project_root(skill_dir)
+    if project_root is None:
+        # Fallback for unusual invocation contexts
+        project_root = find_project_root(Path.cwd())

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In
`@src/workflows/3-technical/gds-game-architecture/scripts/resolve-customization.py`
around lines 148 - 151, The code currently calls find_project_root(Path.cwd())
before falling back to find_project_root(skill_dir), which can pick the wrong
repo; change the order to probe the skill_dir first by calling
find_project_root(skill_dir) and if that returns None then call
find_project_root(Path.cwd()), updating the project_root assignment and any
related comments to reflect the new lookup order (refer to find_project_root,
project_root, skill_dir, and Path.cwd()).

---

130-132: ⚠️ Potential issue | 🟠 Major

Validate skill_name before building override file paths.

Line 160-Line 161 use raw skill_name in filesystem paths. Without validation, path traversal segments can escape _bmad/customizations.

Suggested fix

 import argparse
 import json
+import re
 import sys
 import tomllib
@@
     args = parser.parse_args()
+    if not re.fullmatch(r"[A-Za-z0-9][A-Za-z0-9._-]*", args.skill_name):
+        parser.error(
+            "skill_name must contain only letters, numbers, dot, underscore, or hyphen"
+        )

Also applies to: 160-161

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In
`@src/workflows/3-technical/gds-game-architecture/scripts/resolve-customization.py`
around lines 130 - 132, The code uses the raw skill_name argument when building
filesystem paths under "_bmad/customizations", which allows path traversal;
validate and sanitize skill_name before composing paths: reject or normalize any
value containing path separators or traversal segments ("/", "\", ".."), or
enforce an allowlist/regex (e.g., only alphanumeric, hyphen, underscore) and
raise an error if invalid; alternatively use os.path.basename(skill_name) and
then verify the resulting joined path still resides under the expected base dir
(compare realpath of joined path to realpath of base) before reading/writing.
Ensure these checks are applied wherever the variable skill_name is used to
construct paths.

---

42-51: ⚠️ Potential issue | 🟠 Major

Fail hard when required defaults cannot be loaded.

load_toml at Line 42-Line 51 silently returns {} for missing/invalid files, and Line 154 uses it for required customize.toml. That can produce incomplete config without failing fast.

Suggested fix

-def load_toml(path: Path) -> dict[str, Any]:
-    """Return parsed TOML or empty dict if the file doesn't exist."""
+def load_toml(path: Path, *, required: bool = False) -> dict[str, Any]:
+    """Return parsed TOML; optionally fail if missing/invalid."""
     if not path.is_file():
-        return {}
+        if required:
+            raise FileNotFoundError(f"required TOML not found: {path}")
+        return {}
     try:
         with open(path, "rb") as f:
             return tomllib.load(f)
     except (tomllib.TOMLDecodeError, OSError) as exc:
+        if required:
+            raise RuntimeError(f"failed to parse required TOML {path}: {exc}") from exc
         print(f"warning: failed to parse {path}: {exc}", file=sys.stderr)
         return {}
@@
-    defaults = load_toml(defaults_path)
+    try:
+        defaults = load_toml(defaults_path, required=True)
+    except (FileNotFoundError, RuntimeError) as exc:
+        print(f"error: {exc}", file=sys.stderr)
+        sys.exit(2)

Also applies to: 154-154

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In
`@src/workflows/3-technical/gds-game-architecture/scripts/resolve-customization.py`
around lines 42 - 51, load_toml currently swallows missing/invalid files by
returning {} which allows required configs (like customize.toml) to be silently
ignored; change load_toml to accept a required: bool = False parameter and when
required is True, raise a clear exception (e.g., FileNotFoundError for missing
file or re-raise/wrap tomllib.TOMLDecodeError/OSError) instead of returning {};
then update the code that loads customize.toml to call load_toml(...,
required=True) so the program fails fast when those defaults cannot be loaded.

src/workflows/2-design/gds-create-ux-design/scripts/resolve-customization.py (2)

93-94: ⚠️ Potential issue | 🟠 Major

Restrict merge-by-code behavior to menu only.

Line 93 currently applies merge-by-code to any code-keyed list, not just menu. This can preserve/replace entries unexpectedly in unrelated arrays.

Suggested fix

-        elif _is_menu_array(over_val) and _is_menu_array(base_val):
+        elif key == "menu" and _is_menu_array(over_val) and _is_menu_array(base_val):
             merged[key] = merge_menu(base_val, over_val)  # type: ignore[arg-type]

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/workflows/2-design/gds-create-ux-design/scripts/resolve-customization.py`
around lines 93 - 94, The merge-by-code behavior is currently applied to any
code-keyed list because _is_menu_array(over_val) and _is_menu_array(base_val)
are used irrespective of the dict key; restrict this logic so it only runs when
the key is the literal "menu". Update the conditional that calls merge_menu (the
branch that sets merged[key] = merge_menu(base_val, over_val)) to also check
that key == "menu" (or the appropriate constant) before invoking _is_menu_array
and merge_menu, so other code-keyed arrays are handled by the existing fallback
merge logic.

---

42-51: ⚠️ Potential issue | 🟠 Major

Fail fast when default customization cannot be loaded.

Line 154 treats skill defaults as optional because Lines 42-51 downgrade parse/IO failures to {}. That can silently strip baseline config while still exiting successfully.

Suggested fix

-def load_toml(path: Path) -> dict[str, Any]:
+def load_toml(path: Path, *, required: bool = False) -> dict[str, Any]:
     """Return parsed TOML or empty dict if the file doesn't exist."""
     if not path.is_file():
+        if required:
+            raise FileNotFoundError(path)
         return {}
     try:
         with open(path, "rb") as f:
             return tomllib.load(f)
     except (tomllib.TOMLDecodeError, OSError) as exc:
+        if required:
+            raise
         print(f"warning: failed to parse {path}: {exc}", file=sys.stderr)
         return {}
@@
-    defaults = load_toml(defaults_path)
+    try:
+        defaults = load_toml(defaults_path, required=True)
+    except (FileNotFoundError, tomllib.TOMLDecodeError, OSError) as exc:
+        print(f"error: failed to load defaults from {defaults_path}: {exc}", file=sys.stderr)
+        sys.exit(2)

Also applies to: 154-155

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/workflows/2-design/gds-create-ux-design/scripts/resolve-customization.py`
around lines 42 - 51, The load_toml function currently swallows TOML parse and
IO errors and returns {} which hides real failures; change load_toml so it still
returns {} only when the file does not exist (path.is_file() is False) but for
actual tomllib.TOMLDecodeError or OSError re-raise the exception (or call
sys.exit(1) with a clear error message) so the process fails fast when defaults
can't be loaded; update any callers expecting optional defaults (e.g., the code
that treats skill defaults as optional) to rely on the function raising on real
errors rather than receiving an empty dict.

src/agents/gds-agent-game-scrum-master/scripts/resolve-customization.py (1)

58-64: ⚠️ Potential issue | 🟠 Major

Menu merge fallback still drops base entries when one override item is malformed.

If a single override menu item is invalid, _is_menu_array returns false and deep_merge replaces the entire menu instead of merging valid items and skipping only the bad one. This can silently discard defaults/team entries.

Suggested fix

 def _is_menu_array(value: Any) -> bool:
-    """True when *value* is a non-empty list where ALL items are dicts with a ``code`` key."""
-    return (
-        isinstance(value, list)
-        and len(value) > 0
-        and all(isinstance(item, dict) and "code" in item for item in value)
-    )
+    """True when *value* is a TOML array-of-tables candidate."""
+    return isinstance(value, list) and all(isinstance(item, dict) for item in value)
@@
-        elif _is_menu_array(over_val) and _is_menu_array(base_val):
+        elif key == "menu" and _is_menu_array(base_val) and _is_menu_array(over_val):
             merged[key] = merge_menu(base_val, over_val)  # type: ignore[arg-type]

Also applies to: 93-96

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/agents/gds-agent-game-scrum-master/scripts/resolve-customization.py`
around lines 58 - 64, The current menu-merge logic uses _is_menu_array to decide
whether to replace or merge menus, but if any override item is malformed it
returns False and overwrites the base; change the merge to be resilient by
updating deep_merge (the code that handles menu arrays) to iterate override
items and merge per-item: for each override entry, if isinstance(item, dict) and
"code" in item find matching base entry by code and merge/update it, else if
valid append as new entry, and silently skip malformed entries; alternatively,
make _is_menu_array return True when the list contains at least one valid
dict-with-"code" entry so the per-item merge runs—use the function name
_is_menu_array and the deep_merge logic to locate where to apply this fix.

src/workflows/1-preproduction/gds-brainstorm-game/scripts/resolve-customization.py (2)

129-132: ⚠️ Potential issue | 🟠 Major

Sanitize skill_name before building override paths.

At Line 160 and Line 161, unvalidated skill_name is interpolated into filenames. Inputs like ../... can escape _bmad/customizations and read unintended files.

🔧 Proposed fix

 import argparse
 import json
+import re
 import sys
 import tomllib
 from pathlib import Path
 from typing import Any

+SKILL_NAME_RE = re.compile(r"^[a-z0-9][a-z0-9-]*$")
+
+def _parse_skill_name(value: str) -> str:
+    if not SKILL_NAME_RE.fullmatch(value):
+        raise argparse.ArgumentTypeError("skill_name must match ^[a-z0-9][a-z0-9-]*$")
+    return value
@@
     parser.add_argument(
         "skill_name",
+        type=_parse_skill_name,
         help="Skill identifier (e.g. bmad-agent-pm, bmad-product-brief)",
     )

Also applies to: 160-161

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In
`@src/workflows/1-preproduction/gds-brainstorm-game/scripts/resolve-customization.py`
around lines 129 - 132, Validate and sanitize the skill_name argument before
using it to build override file paths: reject or normalize any input containing
path separators or traversal (e.g., "/" or ".."), for example by replacing with
an allowed pattern or using os.path.basename and then ensuring it matches a
strict whitelist regex like r'^[a-z0-9_-]+$'; when constructing override
filenames (the code that interpolates skill_name into filenames), use
os.path.join with the fixed directory (e.g., "_bmad/customizations") and then
verify the resolved absolute path is inside that directory via os.path.realpath
comparison to prevent directory traversal; if validation fails, raise a clear
error and do not proceed to open/read the file.

---

58-64: ⚠️ Potential issue | 🟠 Major

Malformed menu overrides can still bypass merge-by-code and replace the entire list.

At Line 58 and Line 93, a single override item missing code makes _is_menu_array false, so deep_merge falls back to atomic replacement instead of merge_menu validation/warnings.

🔧 Proposed fix

 def _is_menu_array(value: Any) -> bool:
-    """True when *value* is a non-empty list where ALL items are dicts with a ``code`` key."""
-    return (
-        isinstance(value, list)
-        and len(value) > 0
-        and all(isinstance(item, dict) and "code" in item for item in value)
-    )
+    """True when *value* is a list of dict menu items (possibly empty)."""
+    return isinstance(value, list) and all(isinstance(item, dict) for item in value)

 def merge_menu(base: list[dict], override: list[dict]) -> list[dict]:
     """Merge-by-code: matching codes replace; new codes append."""
+    if override == []:
+        return []
+
     result_by_code: dict[str, dict] = {item["code"]: dict(item) for item in base if "code" in item}
     for item in override:
         if "code" not in item:
             print(f"warning: menu item missing 'code' key, skipping: {item}", file=sys.stderr)
             continue
         result_by_code[item["code"]] = dict(item)
     return list(result_by_code.values())

@@
-        elif _is_menu_array(over_val) and _is_menu_array(base_val):
+        elif key == "menu" and _is_menu_array(over_val) and _is_menu_array(base_val):
             merged[key] = merge_menu(base_val, over_val)  # type: ignore[arg-type]

Also applies to: 93-96

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In
`@src/workflows/1-preproduction/gds-brainstorm-game/scripts/resolve-customization.py`
around lines 58 - 64, The predicate _is_menu_array is too strict (requires every
list item to have "code"), causing deep_merge to atomically replace menus if any
override item lacks a code; change _is_menu_array to return True for a non-empty
list where all items are dicts and at least one item contains a "code" key
(i.e., isinstance(value, list) and len(value) > 0 and all(isinstance(item, dict)
for item in value) and any("code" in item for item in value)); then ensure
merge_menu (the function used by deep_merge) emits warnings or skips/ignores
individual override items that lack a "code" rather than letting the full list
be replaced, so malformed items are reported and valid merge-by-code still
occurs.

src/agents/gds-agent-game-qa/scripts/resolve-customization.py (1)

58-64: ⚠️ Potential issue | 🟠 Major

Menu merge still degrades to full replacement on partially malformed overrides.

At Line 93, merge-by-code only runs if all override items pass _is_menu_array. If one override entry is malformed, Line 96 replaces the whole menu and can drop defaults; warnings at Line 72 are skipped in that path.

Proposed fix

 def merge_menu(base: list[dict], override: list[dict]) -> list[dict]:
     """Merge-by-code: matching codes replace; new codes append."""
-    result_by_code: dict[str, dict] = {item["code"]: dict(item) for item in base if "code" in item}
+    result_by_code: dict[str, dict] = {
+        str(item["code"]): dict(item)
+        for item in base
+        if isinstance(item, dict) and "code" in item
+    }
     for item in override:
-        if "code" not in item:
+        if not isinstance(item, dict) or "code" not in item:
             print(f"warning: menu item missing 'code' key, skipping: {item}", file=sys.stderr)
             continue
-        result_by_code[item["code"]] = dict(item)
+        result_by_code[str(item["code"])] = dict(item)
     return list(result_by_code.values())
@@
-        elif _is_menu_array(over_val) and _is_menu_array(base_val):
-            merged[key] = merge_menu(base_val, over_val)  # type: ignore[arg-type]
+        elif key == "menu" and isinstance(base_val, list) and isinstance(over_val, list):
+            if len(over_val) == 0:
+                merged[key] = []
+            elif any(isinstance(i, dict) and "code" in i for i in over_val):
+                merged[key] = merge_menu(base_val, over_val)
+            else:
+                merged[key] = over_val

Also applies to: 67-75, 93-96

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/agents/gds-agent-game-qa/scripts/resolve-customization.py` around lines
58 - 64, Currently _is_menu_array is used to gate merge-by-code only when all
override items are valid, causing a full replace if any item is malformed;
change the merging logic so that instead of requiring all items pass
_is_menu_array you collect the subset of valid menu entries (items that are
dicts with a "code") and perform merge-by-code for those, emitting warnings for
each malformed entry and only falling back to full replacement when there are
zero valid entries; update the code path that currently checks _is_menu_array
(the merge decision around "merge-by-code" / full-replace) to use this filtered
list and keep existing warning behavior for malformed items.

src/agents/gds-agent-game-solo-dev/scripts/resolve-customization.py (1)

159-161: ⚠️ Potential issue | 🟠 Major

Block path traversal in override file resolution.

Line 160 and Line 161 use raw skill_name in path building. A crafted value can escape _bmad/customizations and read unintended TOML files.

Suggested fix

     if project_root is not None:
         customizations_dir = project_root / "_bmad" / "customizations"
-        team = load_toml(customizations_dir / f"{args.skill_name}.toml")
-        user = load_toml(customizations_dir / f"{args.skill_name}.user.toml")
+        team_path = (customizations_dir / f"{args.skill_name}.toml").resolve()
+        user_path = (customizations_dir / f"{args.skill_name}.user.toml").resolve()
+        base_dir = customizations_dir.resolve()
+        if base_dir not in team_path.parents or base_dir not in user_path.parents:
+            parser.error("invalid skill_name")
+        team = load_toml(team_path)
+        user = load_toml(user_path)

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/agents/gds-agent-game-solo-dev/scripts/resolve-customization.py` around
lines 159 - 161, The code uses args.skill_name directly to build override paths
for load_toml, allowing path traversal; before constructing files from
customizations_dir, validate and sanitize args.skill_name (e.g., reject any path
separators or '..' and enforce a strict whitelist/regex like
/^[A-Za-z0-9_-]+$/), or build the path then resolve it and assert the resulting
path is a child of customizations_dir; apply this check for both
f"{args.skill_name}.toml" and f"{args.skill_name}.user.toml" so load_toml can
only read files inside the _bmad/customizations directory.

src/agents/gds-agent-game-designer/scripts/resolve-customization.py (1)

22-27: ⚠️ Potential issue | 🟠 Major

Path traversal hardening is still missing for skill_name.

Line 160 and Line 161 still compose paths from raw args.skill_name without validation or directory-boundary enforcement. This can escape _bmad/customizations.

Also applies to: 140-161

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/agents/gds-agent-game-designer/scripts/resolve-customization.py` around
lines 22 - 27, The code constructs paths directly from args.skill_name (in
resolve-customization.py around the path creation at lines referenced) allowing
path traversal; validate and restrict skill_name before composing paths: ensure
skill_name matches a safe pattern (e.g. only alphanumeric, underscores, hyphens,
dots) or use os.path.basename to strip separators, then build the path under the
canonical base (e.g. base_dir = Path("_bmad/customizations").resolve()) and
after joining call .resolve() on the resulting Path and verify the resolved path
is a subpath of base_dir (compare with parents or str prefix) before using it;
update the logic around the variables that form the skill_dir/customization path
to enforce these checks and raise an error if validation fails.

src/agents/gds-agent-game-qa/scripts/resolve-customization.py (1)

130-132: Prevent silent cross-skill merges by validating skill_name.

Line 145 always loads defaults for the current skill directory, but Line 160 and Line 161 load overrides using CLI skill_name. A typo can silently merge mismatched files.

Proposed safeguard

     args = parser.parse_args()
@@
     script_dir = Path(__file__).resolve().parent
     skill_dir = script_dir.parent
     defaults_path = skill_dir / "customize.toml"
+    expected_skill_name = skill_dir.name
+    if args.skill_name != expected_skill_name:
+        parser.error(
+            f"skill_name '{args.skill_name}' does not match this skill directory "
+            f"('{expected_skill_name}')"
+        )

Also applies to: 143-146, 160-161

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/agents/gds-agent-game-qa/scripts/resolve-customization.py` around lines
130 - 132, The script currently loads defaults from the current skill directory
but then applies overrides using the CLI parameter skill_name, which allows
typos to silently merge across skills; before loading overrides (the code paths
that read defaults and then apply CLI overrides), validate that the provided
skill_name exactly matches the skill discovered from the current working
directory (or canonical skill id derived from the defaults dir), and if they
differ raise an error and exit; also trim/normalize skill_name (lowercase, strip
whitespace) to avoid trivial mismatches and apply this check wherever the code
reads defaults and then loads overrides using skill_name to prevent cross-skill
merges.

src/workflows/3-technical/gds-check-implementation-readiness/scripts/resolve-customization.py (1)

42-51: Consider a strict mode for TOML parse/read failures.

Returning {} for malformed customization files can silently run workflows with unintended defaults. A --strict mode would make this safer without forcing a breaking default.

🛠️ Suggested pattern

-def load_toml(path: Path) -> dict[str, Any]:
+def load_toml(path: Path, *, strict: bool = False) -> dict[str, Any]:
     """Return parsed TOML or empty dict if the file doesn't exist."""
     if not path.is_file():
         return {}
     try:
         with open(path, "rb") as f:
             return tomllib.load(f)
     except (tomllib.TOMLDecodeError, OSError) as exc:
-        print(f"warning: failed to parse {path}: {exc}", file=sys.stderr)
+        message = f"failed to parse {path}: {exc}"
+        if strict:
+            raise SystemExit(message)
+        print(f"warning: {message}", file=sys.stderr)
         return {}

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In
`@src/workflows/3-technical/gds-check-implementation-readiness/scripts/resolve-customization.py`
around lines 42 - 51, The load_toml function currently swallows parse/read
errors and returns {} which can hide malformed customization files; add an
opt-in strict mode so failures fail fast. Change load_toml signature to accept
strict: bool = False, and in the except block either re-raise the caught
exception (or call sys.exit(1) after printing the error) when strict is True,
otherwise keep the current warning+{} behavior; also wire a new CLI flag (e.g.,
--strict) in the script's argument parsing and pass that flag into load_toml so
callers can opt into strict parsing. Ensure references to load_toml in this
script are updated to pass the strict value.

src/workflows/3-technical/gds-create-epics-and-stories/scripts/resolve-customization.py (1)

148-151: Prefer resolving project root from skill_dir before cwd.

Using cwd first can pick the wrong repository when this script is invoked from another directory. skill_dir is the more reliable anchor for this skill-local script.

♻️ Proposed refactor

-    project_root = find_project_root(Path.cwd())
-    if project_root is None:
-        # Try from the skill directory as fallback
-        project_root = find_project_root(skill_dir)
+    project_root = find_project_root(skill_dir)
+    if project_root is None:
+        # Fallback for unusual invocation contexts
+        project_root = find_project_root(Path.cwd())

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In
`@src/workflows/3-technical/gds-create-epics-and-stories/scripts/resolve-customization.py`
around lines 148 - 151, The current logic finds the project root via
find_project_root(Path.cwd()) before falling back to
find_project_root(skill_dir); change it to prefer find_project_root(skill_dir)
first and only call find_project_root(Path.cwd()) as a fallback so the script
resolves the repository relative to the skill directory; update the assignment
for project_root and the conditional branches around find_project_root,
referencing the existing symbols project_root, find_project_root, skill_dir, and
Path.cwd().

src/agents/gds-agent-game-dev/scripts/resolve-customization.py (1)

1-183: Consider centralizing resolver logic to reduce drift.

This script is duplicated across multiple agents with near-identical logic. Moving it to a shared module/script would lower maintenance risk and keep security fixes consistent.

🤖 Prompt for AI Agents

Verify each finding against the current code and only fix it if needed.

In `@src/agents/gds-agent-game-dev/scripts/resolve-customization.py` around lines
1 - 183, The resolver logic in resolve-customization.py is duplicated across
agents; extract the core functions (find_project_root, load_toml,
_is_menu_array, merge_menu, deep_merge, extract_key and the TOML/merge
semantics) into a shared library module (e.g., bmad.customization.resolver) and
have this script become a thin CLI wrapper that imports and calls the shared
resolve function (preserving the same CLI args, file discovery order, and JSON
output), update other agents to import the same module, and add a small
compatibility shim or tests to ensure behavior of deep_merge/merge_menu and key
extraction remains identical.

Fix all unresolved CodeRabbit comments on this PR:

• Push a commit to this branch (recommended)
• Create a new PR with the fixes