ma-agents 3.4.8 → 3.5.0

package/_bmad-output/implementation-artifacts/4-1-vs-agent-registry-entry.md

@@ -0,0 +1,173 @@
+# Story 4.1: Visual Studio Agent Registry Entry
+
+Status: ready-for-dev
+
+<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
+
+## Story
+
+As a **Chief Architect**,
+I want to understand how Visual Studio exposes AI agent configuration and add VS as a supported agent,
+So that engineers can install skills into Visual Studio's AI assistant.
+
+## Acceptance Criteria
+
+1. **Given** Visual Studio has GitHub Copilot integration
+   **When** the integration mechanism is investigated
+   **Then** a technical note is produced documenting:
+   - Where VS stores AI agent instructions (file paths, config directories)
+   - What format VS expects (markdown, JSON, YAML, or other)
+   - How VS Copilot Chat extensions handle custom instructions
+   - Whether `.vs/` directory, `.editorconfig`, or another mechanism is used
+   - Platform path differences (Windows-only or cross-platform VS Code distinction)
+
+2. **Given** the research is complete
+   **When** the findings are documented
+   **Then** a clear recommendation exists for the agent registry configuration object fields
+
+3. **Given** the VS agent configuration is understood
+   **When** a new agent object is added to `lib/agents.js`
+   **Then** it includes: name, category, platform paths, instruction file, and resource map
+   **And** no changes are needed to `installer.js` or other modules (NFR13)
+
+4. **Given** the VS agent is registered
+   **When** `npx ma-agents list --agents` is run
+   **Then** Visual Studio appears in the agent list
+
+5. **Given** a skill is installed targeting the VS agent
+   **When** the install completes
+   **Then** skill content is placed in the correct VS configuration directory
+   **And** the manifest tracks the VS agent installation
+
+> **Note:** AC #5 overlaps with Story 4-2 scope. Verify basic install here; detailed template resolution and multi-agent testing belongs in 4-2.
+
+## Tasks / Subtasks
+
+- [ ] Task 1: Research Visual Studio AI agent configuration (AC: #1, #2)
+  - [ ] 1.1: Investigate GitHub Copilot in Visual Studio (not VS Code) — how custom instructions are configured
+  - [ ] 1.2: Check for `.github/copilot/copilot.md` support in VS (this is the VS Code Copilot instruction file per `lib/agents.js:79` — does VS use the same mechanism?)
+  - [ ] 1.3: Investigate VS-specific paths: `.vs/` directory, `%APPDATA%/Microsoft/VisualStudio/`, or solution-level config
+  - [ ] 1.4: Check if VS supports `.editorconfig`-adjacent AI instruction files
+  - [ ] 1.5: Document findings in `_bmad-output/implementation-artifacts/vs-agent-research.md`
+  - [ ] 1.6: Produce recommendation for agent registry object fields matching the actual schema: `id`, `name`, `version`, `category`, `description`, `getProjectPath()`, `getGlobalPath()`, `fileExtension`, `template`, `instructionFiles[]`, and optionally `resourceMap`
+- [ ] Task 2: Add VS agent to registry (AC: #3, #4)
+  - [ ] 2.1: Add agent configuration object to the agents array in `lib/agents.js` (search: `const agents = [`)
+  - [ ] 2.2: Set `id`, `name`, `version`, `category` ("ide"), `description`, `fileExtension`, `template` based on research findings
+  - [ ] 2.3: Implement `getProjectPath()` and `getGlobalPath()` functions with platform-specific paths (follow pattern from existing agents — Windows/macOS/Linux branches using `os.platform()`)
+  - [ ] 2.4: Set `instructionFiles` array based on VS's instruction file path
+  - [ ] 2.5: Add `resourceMap` only if VS uses non-standard directory names (like Cline does at `agents.js:122-125`) — otherwise omit
+  - [ ] 2.6: Verify no changes needed to `installer.js` — the installer should pick up the new agent automatically (NFR13)
+  - [ ] 2.5: Run `npx ma-agents list --agents` — verify VS appears
+- [ ] Task 3: Test skill installation to VS agent (AC: #5)
+  - [ ] 3.1: Install a skill targeting the VS agent
+  - [ ] 3.2: Verify files are placed in the correct VS configuration directory
+  - [ ] 3.3: Verify manifest tracks the VS installation
+  - [ ] 3.4: Test on Windows (VS is primarily Windows — macOS VS for Mac is deprecated)
+
+## Dev Notes
+
+### Epic Scope Note
+
+This story combines Epic 4 Story 4.1 (research) and Story 4.2 (add to registry) from the epics file into a single story. The companion story 4-2 covers template format verification — a scope not defined in the original epics. This was an intentional consolidation: research without registry implementation is incomplete, and template verification is a natural second story.
+
+### Architecture Compliance
+
+- **Adding a new agent = adding one object to the registry array.** No installer code changes needed. This is the core extensibility model. [Source: architecture.md#Extensibility-Model, NFR13]
+- **Agent registry in `agents.js`:** Pure data + path functions. Each agent is a configuration object: name, category, platform paths, instruction file, resource map. [Source: architecture.md#Module-Boundaries]
+- **Platform path centralization:** All platform awareness lives in `agents.js`. The installer uses `agents.js` for path resolution and is format-agnostic. [Source: architecture.md#Enforcement-Guidelines]
+
+### Existing Agent Registry Pattern
+
+Follow the exact pattern of existing agents. Example from the `copilot` agent in `lib/agents.js:60-80` (closest to VS):
+
+```javascript
+{
+  id: 'copilot',
+  name: 'GitHub Copilot',
+  version: '1.0.0',
+  category: 'ide',
+  description: 'GitHub Copilot Agent Mode',
+  getProjectPath: () => path.join(process.cwd(), '.github', 'copilot', 'skills'),
+  getGlobalPath: () => {
+    const platform = os.platform();
+    if (platform === 'win32') {
+      return path.join(os.homedir(), 'AppData', 'Roaming', 'GitHub Copilot', 'skills');
+    } else if (platform === 'darwin') {
+      return path.join(os.homedir(), 'Library', 'Application Support', 'GitHub Copilot', 'skills');
+    } else {
+      return path.join(os.homedir(), '.config', 'github-copilot', 'skills');
+    }
+  },
+  fileExtension: '.md',
+  template: 'generic',
+  instructionFiles: ['.github/copilot/copilot.md']
+}
+```
+
+**Note:** Only `cline` has a `resourceMap` field (maps `references` → `docs`, `assets` → `templates`). All other agents omit it. Only add `resourceMap` for VS if research shows it uses non-standard directory names.
+
+The VS agent may use the same `.github/copilot/copilot.md` path if VS and VS Code share the same Copilot instruction mechanism. Research (Task 1) will determine this.
+
+### Research Priorities
+
+**Most likely outcome:** VS uses `.github/copilot/copilot.md` (same as VS Code Copilot — see `lib/agents.js:79`). In this case:
+- The existing `copilot` agent may already cover VS
+- Or VS may need a separate entry with the same paths but a different `id`/`name` for clarity
+- Check if VS has additional instruction files beyond what VS Code supports
+
+**Alternative outcomes:**
+- VS uses `.vs/` directory for AI instructions (solution-level)
+- VS uses `%APPDATA%` paths for user-level AI config
+- VS has its own instruction format (not markdown)
+
+### Windows-Only Consideration
+
+Visual Studio is Windows-only (macOS Visual Studio for Mac was discontinued in 2024). The agent registry entry should:
+- Set platform paths for Windows only (or gracefully skip on macOS/Linux)
+- Use Windows-style paths where needed (though `path.join()` handles this automatically)
+- Consider that the `copilot` agent already handles `.github/` paths cross-platform
+
+### Phase 2 Injection Strategy (NOT YET IMPLEMENTED)
+
+**Note:** `injectionStrategy` is a Phase 2 planned feature from architecture decision P2-1. It does NOT exist in the current codebase. When Phase 2 is implemented, the VS agent may gain:
+
+```javascript
+injectionStrategy: {
+  position: 'top',
+  skipPatterns: ['---']  // skip YAML frontmatter
+}
+```
+
+For this story, focus on the current agent schema fields only. The `injectionStrategy` will be added in a separate Phase 2 epic.
+
+### Critical Guardrails
+
+- **Only modify `lib/agents.js`** — no changes to installer.js, cli.js, or bmad.js [Source: architecture.md, NFR13]
+- **Use `path.join()` for all paths** [Source: architecture.md#Enforcement-Guidelines]
+- **No `process.platform` checks outside agents.js** — use `os.platform()` inside `getProjectPath()`/`getGlobalPath()` only [Source: architecture.md#Anti-Patterns]
+- **No new npm dependencies** [Source: architecture.md#Anti-Patterns]
+
+### Project Structure Notes
+
+- Files to modify: `lib/agents.js` (add agent entry)
+- Files to create: `_bmad-output/implementation-artifacts/vs-agent-research.md` (research findings)
+- No changes to installer, CLI, or BMAD modules
+
+### References
+
+- [Source: _bmad-output/planning-artifacts/epics.md#Epic-4] — Story 4.1 and 4.2 definitions
+- [Source: _bmad-output/planning-artifacts/prd.md#IDE-Agent-Integration-Model] — VS listed as gap
+- [Source: _bmad-output/planning-artifacts/architecture.md#Extensibility-Model] — Agent registry model (NFR13)
+- [Source: _bmad-output/planning-artifacts/architecture.md#Decision-P2-1] — Injection strategy pattern
+- [Source: _bmad-output/planning-artifacts/architecture.md#Module-Boundaries] — agents.js responsibility
+- [Source: lib/agents.js] — Current agent registry (11 agents: 7 IDE + 4 BMAD)
+
+## Dev Agent Record
+
+### Agent Model Used
+
+### Debug Log References
+
+### Completion Notes List
+
+### File List

package/_bmad-output/implementation-artifacts/4-2-vs-skill-template-format.md

@@ -0,0 +1,129 @@
+# Story 4.2: Visual Studio Skill Template Format
+
+Status: ready-for-dev
+
+<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
+<!-- Dependency: Story 4-1 must be completed first (research findings determine this story's implementation) -->
+
+## Story
+
+As an **engineer**,
+I want skills to install correctly into Visual Studio with proper format translation,
+So that my VS AI assistant receives the same methodology content as other agents.
+
+## Acceptance Criteria
+
+1. **Given** a skill with no VS-specific template exists
+   **When** installed to the VS agent
+   **Then** the `SKILL.md` fallback content is used (standard template resolution chain)
+   **And** the content is valid for VS's expected format
+
+2. **Given** VS requires a format different from standard markdown
+   **When** a skill needs VS-specific content
+   **Then** a `visual-studio.md` (or format-appropriate) template can be added to the skill
+   **And** the template resolution chain picks it up automatically
+
+3. **Given** skills are installed to both VS and other agents simultaneously
+   **When** the install completes
+   **Then** each agent receives the correct format (VS-specific or fallback)
+   **And** the manifest tracks both installations independently
+
+4. **Given** the VS agent has resource mapping rules
+   **When** a skill with `references/` or `assets/` is installed
+   **Then** supporting files are mapped to the correct VS directories per the resource map
+
+## Tasks / Subtasks
+
+- [ ] Task 1: Determine VS template requirements (AC: #1, #2)
+  - [ ] 1.1: Based on Story 4-1 research, determine if VS needs a format different from standard markdown
+  - [ ] 1.2: If VS uses markdown (like most agents): no template format work needed — SKILL.md fallback works
+  - [ ] 1.3: If VS needs a different format: define the template transformation requirements
+  - [ ] 1.4: Determine the template filename: likely `visual-studio.md` matching the agent registry key
+- [ ] Task 2: Define resource mapping for VS (AC: #4)
+  - [ ] 2.1: Based on Story 4-1 research, determine where VS expects supporting files (references/, assets/)
+  - [ ] 2.2: **Only if VS uses non-standard directory names**: add `resourceMap` to the VS agent entry in `lib/agents.js`. Currently only `cline` has a resourceMap (maps `references` → `docs`, `assets` → `templates` at `agents.js:122-125`). Example:
+    ```javascript
+    resourceMap: {
+      'references': 'docs',
+      'assets': 'templates'
+    }
+    ```
+  - [ ] 2.3: If VS uses standard directory names (`references/`, `assets/`), **omit `resourceMap` entirely** — do not set to null/empty (follow pattern of the other 10 agents that have no resourceMap)
+- [ ] Task 3: Test template resolution for VS (AC: #1, #2, #3)
+  - [ ] 3.1: Install a skill WITHOUT a VS template — verify SKILL.md fallback works
+  - [ ] 3.2: If VS-specific template created: install a skill WITH a VS template — verify template is used
+  - [ ] 3.3: Install skills to VS + another agent simultaneously — verify both get correct content
+  - [ ] 3.4: Verify manifest tracks VS installations correctly
+- [ ] Task 4: Create VS-specific templates for critical skills (AC: #2) — if needed
+  - [ ] 4.1: If VS needs format-specific templates, create them for high-priority skills (e.g., `git-workflow-skill`, `code-documentation`)
+  - [ ] 4.2: If VS uses standard markdown, this task is a no-op — SKILL.md fallback is sufficient
+
+## Dev Notes
+
+### Epic Scope Note
+
+This story covers template format verification — a scope not in the original epics (which defined 4.2 as "Add Visual Studio Agent to Registry"). The registry addition is handled in Story 4-1. This story focuses on ensuring the template resolution chain works correctly for the VS agent.
+
+### Architecture Compliance
+
+- **Template resolution chain:** `templates/<agent-id>.md` -> `templates/generic.md` -> `SKILL.md`. The template filename must match the agent's `id` field in `agents.js` (e.g., if VS agent has `id: 'visual-studio'`, then template is `templates/visual-studio.md`). The `template` field on the agent config specifies which template to use as default (e.g., `template: 'generic'`). [Source: architecture.md#Extensibility-Model]
+- **Adding a new agent target must not require changes to existing skills** (NFR11). The SKILL.md fallback ensures all existing skills work with VS out of the box.
+- **Resource mapping** is optional per-agent in the registry. Only `cline` currently uses it. The installer reads resourceMap from agents.js if present and remaps directory names accordingly. [Source: architecture.md#Module-Boundaries, lib/agents.js:122-125]
+
+### Dependency on Story 4-1
+
+This story **cannot be implemented** until Story 4-1's research is complete. The research determines:
+1. Whether VS needs a different format (markdown vs JSON vs other)
+2. Where VS expects skill files (directory paths)
+3. How resources (references, assets) are mapped
+4. What the template filename should be
+
+**If VS uses `.github/copilot-instructions.md`** (same as VS Code Copilot):
+- This story is minimal — the existing `copilot` agent template format already works
+- Resource mapping may already be defined in the `copilot` agent entry
+- The main work is verifying the existing template chain works for VS
+
+**If VS has a unique configuration mechanism:**
+- Template format definition is needed
+- Resource mapping must be researched and configured
+- Some skills may need VS-specific templates
+
+### Most Likely Scenario
+
+VS Copilot likely shares the `.github/copilot-instructions.md` mechanism with VS Code. In this case:
+- All existing skills work via SKILL.md fallback (no VS templates needed)
+- Skills with `copilot.md` templates work for both VS and VS Code
+- This story becomes primarily a verification/testing story
+
+### Critical Guardrails
+
+- **Do not modify existing skills** unless VS genuinely needs a different format [Source: NFR11]
+- **Only modify `lib/agents.js`** for resource mapping updates [Source: architecture.md, NFR13]
+- **Use `path.join()` for all paths** [Source: architecture.md#Enforcement-Guidelines]
+- **No new npm dependencies** [Source: architecture.md#Anti-Patterns]
+
+### Project Structure Notes
+
+- Files to modify: `lib/agents.js` (resource map update for VS agent — may already be done in 4-1)
+- Files to create: VS-specific templates in individual skills ONLY if research shows VS needs them
+- No changes to installer logic, CLI, or BMAD modules
+
+### References
+
+- [Source: _bmad-output/planning-artifacts/epics.md#Epic-4] — Story 4.2 definition
+- [Source: _bmad-output/planning-artifacts/prd.md#IDE-Agent-Integration-Model] — Agent integration points table
+- [Source: _bmad-output/planning-artifacts/architecture.md#Extensibility-Model] — Template resolution priority chain
+- [Source: _bmad-output/planning-artifacts/architecture.md#Module-Boundaries] — agents.js resource mapping
+- [Source: _bmad-output/planning-artifacts/prd.md#NFR11] — New agents don't require changes to existing skills
+- [Source: lib/agents.js] — Agent registry with resource maps
+- [Source: _bmad-output/implementation-artifacts/4-1-vs-agent-registry-entry.md] — Prerequisite story
+
+## Dev Agent Record
+
+### Agent Model Used
+
+### Debug Log References
+
+### Completion Notes List
+
+### File List

package/_bmad-output/implementation-artifacts/5-5-explicit-parameter-passing.md

@@ -0,0 +1,274 @@
+# Story 5.5: Explicit Parameter Passing to bmad-method
+
+Status: review
+
+<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
+<!-- Epic: 5 — Bundled BMAD Installation (Phase 2) -->
+<!-- Sprint Phase: Phase A — Installation Fixes (next release) -->
+<!-- Dependencies: Stories 5.1-5.4 (all done). Story 5.6 (space-in-path) shares same code — coordinate. -->
+
+## Story
+
+As a **DevOps engineer**,
+I want ma-agents to pass all collected installation parameters to bmad-method as explicit CLI flags,
+so that BMAD is fully configured for all selected platforms (including OpenCode) without relying on the broken silent install mode.
+
+## Acceptance Criteria
+
+1. **Given** the user selects platforms during the ma-agents wizard (e.g., claude-code, cursor, opencode)
+   **When** bmad.js invokes bmad-method
+   **Then** it passes `--tools claude-code,cursor,opencode` explicitly
+   **And** bmad-method configures all selected platforms correctly
+
+2. **Given** the user provides their name and language preference during the ma-agents wizard
+   **When** bmad.js invokes bmad-method
+   **Then** it passes `--user-name`, `--communication-language`, `--document-output-language`, and `--output-folder` as explicit flags
+   **And** bmad-method uses these values without prompting
+
+3. **Given** all BMAD-relevant parameters are passed as explicit CLI flags
+   **When** the `--yes` flag is also included
+   **Then** bmad-method skips prompts only for parameters already supplied via flags
+   **And** applies its own defaults for any new parameters ma-agents hasn't mapped (FR125)
+   **And** no interactive BMAD prompt appears to the user (FR126)
+
+4. **Given** the installer runs in CI/CD mode (`--yes --force`)
+   **When** bmad.js constructs the bmad-method command
+   **Then** it uses the same `buildBmadArgs()` function with pre-determined default answers
+   **And** produces identical BMAD configuration as interactive mode (FR127)
+
+5. **Given** the extension module exists at `lib/bmad-extension/`
+   **When** bmad.js invokes bmad-method
+   **Then** it passes `--custom-content` with the quoted path to the extension module
+   **And** bmad-method validates the module.yaml and deploys the extension
+
+6. **Given** bmad-method is invoked with `--action update` for existing installations
+   **When** the update completes
+   **Then** all explicit parameters are applied to the update
+   **And** existing customizations are preserved per bmad-method's update behavior
+
+## Tasks / Subtasks
+
+- [x] Task 1: Create `buildBmadArgs()` function in `lib/bmad.js` (AC: #1, #2, #3, #5)
+  - [x] 1.1 Define `buildBmadArgs(installContext)` that returns a complete command string
+  - [x] 1.2 Map all available parameters to bmad-method CLI flags (see parameter mapping table below)
+  - [x] 1.3 Quote ALL path arguments with double quotes for space-in-path safety (AC ties to Story 5.6)
+  - [x] 1.4 Always include `--yes` flag to suppress interactive prompts
+  - [x] 1.5 Include `--custom-content` pointing to `lib/bmad-extension/` if it exists
+- [x] Task 2: Update `installBmad()` to use `buildBmadArgs()` (AC: #1, #2, #3)
+  - [x] 2.1 Replace string-concatenation command building with `buildBmadArgs()` call
+  - [x] 2.2 Pass `action: 'install'` in the install context
+  - [x] 2.3 Verify `prePopulateBmadCache(force)` still runs BEFORE execSync
+- [x] Task 3: Update `updateBmad()` to use `buildBmadArgs()` (AC: #6)
+  - [x] 3.1 Replace string-concatenation command building with `buildBmadArgs()` call
+  - [x] 3.2 Pass `action: 'update'` in the install context
+- [x] Task 4: Update `applyCustomizations()` recompile step to use `buildBmadArgs()` (AC: #3, #4)
+  - [x] 4.1 Replace the recompile command at current line ~130 with `buildBmadArgs()` call
+  - [x] 4.2 This call uses `action: 'install'` (it's a recompile, not update)
+- [x] Task 5: Update function signatures to accept install context (AC: #2, #4)
+  - [x] 5.1 Add `userName`, `commLang`, `docLang`, `outputFolder` parameters (with defaults)
+  - [x] 5.2 Verify `cli.js` call sites are backward-compatible with new optional params (no changes needed — defaults apply)
+  - [x] 5.3 Ensure CI/CD path (`--yes`) uses same `buildBmadArgs()` with default values (FR127)
+- [x] Task 6: Manual smoke test (AC: #1-#6)
+  - [x] 6.1 Run `npx ma-agents install --yes` and verify command output includes all explicit flags
+  - [x] 6.2 Verify `_bmad/` output includes all expected modules and tool configurations
+  - [x] 6.3 Test update path on existing installation
+
+## Dev Notes
+
+### Core Change: Replace ad-hoc command building with `buildBmadArgs()`
+
+The current `lib/bmad.js` builds bmad-method commands via string concatenation in 3 places (lines 26, 52, 130). Each duplicates the pattern: `getBmadCommand('install --yes --directory "..."')` + manual `+= --modules` + manual `+= --tools`. This story replaces all 3 with a single `buildBmadArgs(installContext)` function per architecture Decision P2-6.
+
+### Current State of `lib/bmad.js` (428 lines)
+
+**3 command construction sites to replace:**
+
+| Function | Line | Current pattern | Action flag |
+|---|---|---|---|
+| `installBmad()` | 26 | `getBmadCommand('install --yes --directory "..."')` + modules + tools | `install` |
+| `updateBmad()` | 52 | `getBmadCommand('install --action update --yes --directory "..."')` + modules + tools | `update` |
+| `applyCustomizations()` | 130 | `getBmadCommand('install --yes --directory "..."')` + modules + tools | `install` (recompile) |
+
+**What is NOT changing:**
+- `getBmadCommand(args)` stays — it resolves `bmad-npx-wrapper.js` via `require.resolve()` (Story 5.1)
+- `prePopulateBmadCache(force)` stays — cache pre-population logic is correct (Story 5.3)
+- `deployMethodology()` stays — runs AFTER execSync, unrelated to parameter passing
+- `restoreGitDir()` stays — internal cache helper
+- `applyCustomizations()` stages 1-7 (file copy, extension deploy, workflow deploy) stay — only the recompile execSync changes
+
+### `buildBmadArgs()` Reference Implementation (from Architecture P2-6)
+
+```javascript
+function buildBmadArgs(installContext) {
+  const bmadPath = require.resolve('bmad-method/tools/bmad-npx-wrapper.js');
+  const args = [
+    'node', `"${bmadPath}"`, 'install',
+    '--directory', `"${installContext.projectRoot}"`,
+    '--modules', installContext.modules.join(','),
+    '--tools', installContext.tools.length > 0 ? installContext.tools.join(',') : 'none',
+    '--yes',
+  ];
+  // Optional params — only include if provided (let bmad-method default otherwise)
+  if (installContext.userName) {
+    args.push('--user-name', `"${installContext.userName}"`);
+  }
+  if (installContext.commLang) {
+    args.push('--communication-language', installContext.commLang);
+  }
+  if (installContext.docLang) {
+    args.push('--document-output-language', installContext.docLang);
+  }
+  if (installContext.outputFolder) {
+    args.push('--output-folder', installContext.outputFolder);
+  }
+  // Extension module — only if directory exists
+  const extensionPath = path.join(__dirname, 'bmad-extension');
+  if (fs.existsSync(extensionPath)) {
+    args.push('--custom-content', `"${extensionPath}"`);
+  }
+  if (installContext.action === 'update') {
+    args.push('--action', 'update');
+  }
+  return args.join(' ');
+}
+```
+
+### Parameter Mapping Table (FR123)
+
+| ma-agents source | bmad-method flag | Current state | Notes |
+|---|---|---|---|
+| `projectRoot` (detected) | `--directory` | Already passed (Story 5.4 fix) | **Must quote for spaces** |
+| `tools` array from wizard | `--tools` | Already passed | Fixes OpenCode bug — previously not configured |
+| `modules` array | `--modules` | Already passed | Default: `['bmm', 'bmb']` |
+| `userName` | `--user-name` | **NOT passed** — new | Optional; let bmad-method default if absent |
+| `commLang` | `--communication-language` | **NOT passed** — new | Optional; defaults to "English" |
+| `docLang` | `--document-output-language` | **NOT passed** — new | Optional; defaults to "English" |
+| `outputFolder` | `--output-folder` | **NOT passed** — new | Optional; defaults to "_bmad-output" |
+| extension module path | `--custom-content` | **NOT passed** — new | Path to `lib/bmad-extension/`; quote for spaces |
+| install vs update | `--action` | Already passed for update | `install` (default) or `update` |
+| `--yes` | `--yes` | Already passed | Suppresses prompts for supplied params only |
+
+### bmad-method v6.0.4 CLI Flags (Verified from `node_modules`)
+
+From `node_modules/bmad-method/tools/cli/commands/install.js` lines 14-26:
+```
+--directory <path>               Installation directory
+--modules <modules>              Comma-separated list of module IDs
+--tools <tools>                  Comma-separated list of tools/IDEs
+--custom-content <paths>         Comma-separated list of custom module paths
+--action <type>                  install, update, quick-update, compile-agents
+--user-name <name>               Name for agents to use
+--communication-language <lang>  Language for agent communication
+--document-output-language <lang> Language for document output
+--output-folder <path>           Output folder relative to project root
+-y, --yes                        Accept all defaults and skip prompts
+```
+
+### Critical: `--custom-content` Replaces Manual Extension Deployment
+
+Currently `applyCustomizations()` manually copies `lib/bmad-extension/` to `_bmad/extensions/ma-agents-skills/` (lines 156-162). With `--custom-content`, bmad-method handles this natively. **However**, the manual copy may still be needed for the recompile step in `applyCustomizations()` if bmad-method's `--custom-content` doesn't deploy to the same target path. Verify during implementation:
+- Does `--custom-content` deploy to `_bmad/extensions/<module-name>/`?
+- If yes: the manual `fs.copy` at line 160 can be removed (bmad-method handles it)
+- If no: keep the manual copy AND pass `--custom-content` (belt-and-suspenders)
+
+### Wizard Gap: `userName`, `commLang`, `docLang` Not Collected
+
+The `bin/cli.js` wizard does NOT currently prompt for user name, communication language, document output language, or output folder. These are new parameters from FR123. For this story:
+- Add the new params to function signatures with sensible defaults
+- Pass defaults to `buildBmadArgs()` — bmad-method's `--yes` behavior will apply its own defaults for unprovided params
+- **Do NOT add wizard prompts in this story** — that's a future enhancement. The goal is to stop the silent install from skipping config, not to collect new data from users yet.
+
+### Three Bugs This Story Fixes
+
+1. **OpenCode not configured**: `--tools` explicitly lists all selected platforms including opencode (currently tools ARE passed, but this ensures consistency through `buildBmadArgs()`)
+2. **Spaces in paths**: All path arguments quoted in `buildBmadArgs()` — `--directory "d:\My Projects\agents"` (ties to Story 5.6)
+3. **Silent install skips config**: `--yes` combined with explicit flags means bmad-method applies full config from flags, defaults only for unmapped params
+
+### Project Structure Notes
+
+- **Primary file**: `lib/bmad.js` — all changes in this file (existing 428 lines)
+- **Secondary file**: `bin/cli.js` — update call sites to pass new optional params (existing patterns)
+- **No new files created**
+- **No new dependencies**
+- Extension module at `lib/bmad-extension/` stays unchanged — just referenced by `--custom-content`
+
+### References
+
+- [Source: architecture.md, Decision P2-6] — Full `buildBmadArgs()` architecture with parameter mapping table
+- [Source: epics.md, Story 5.5 lines 531-577] — Acceptance criteria and technical notes
+- [Source: epics.md, Story 5.6 lines 578-603] — Space-in-path bug fix (shares code with this story)
+- [Source: prd.md, FR123-FR127] — Explicit parameter passing requirements
+- [Source: prd.md, NFR20-NFR21] — Version pinning and deterministic installation
+- [Source: lib/bmad.js lines 25-49] — Current `installBmad()` implementation
+- [Source: lib/bmad.js lines 51-75] — Current `updateBmad()` implementation
+- [Source: lib/bmad.js lines 77-200] — Current `applyCustomizations()` with recompile at line 130
+- [Source: node_modules/bmad-method/tools/cli/commands/install.js lines 14-26] — Verified CLI flag definitions
+- [Source: bin/cli.js lines 374-432] — Call sites for installBmad/updateBmad/applyCustomizations
+- [Source: 5-4-validate-bundled-installation.md] — Previous story: critical `--directory` bug fix, validation results
+
+## Previous Story Intelligence (5.4)
+
+**Critical bug found and fixed**: All 3 `getBmadCommand()` callsites were missing `--directory "${projectRoot}"`. bmad-method v6.0.4 only skips the directory prompt when `--directory` is explicitly provided; without it, non-TTY `execSync` silently exits with code 0 and no `_bmad/` is created. This was fixed in Story 5.4.
+
+**Learnings to apply:**
+- bmad-method silently succeeds when params are missing — always verify `_bmad/` output after install
+- The `--directory` parameter MUST be quoted for paths with spaces (discovered but not fully fixed in 5.4 — this story completes the fix)
+- `force` parameter must thread through all callsites — verify `buildBmadArgs()` doesn't drop it
+- The `ac#3 status gap` (BMAD module status not surfaced by `npx ma-agents status`) is out of scope
+
+**From Story 5.3 code review:**
+- `prePopulateBmadCache()` removed `projectRoot` param — call is `prePopulateBmadCache(force)` only
+- `fs.existsSync()` replaced with `await fs.pathExists()` — use async consistently
+- Summary log only prints when `copied > 0 || replaced > 0` — correct behavior
+
+## Git Intelligence
+
+Recent commits (descending):
+```
+998fa13 docs(planning): add F9 migration, F10 multi-repo, F6 explicit params, Epic 17 sprint rework
+8e88686 chore(release): bump version to 2.21.0
+63610de feat(epic-13): auto-generate project-context.md at install time
+```
+
+Current version: **2.21.0**. bmad-method pinned at **6.0.4** in `package.json` line 29.
+
+No recent code changes to `lib/bmad.js` since Story 5.4 — the file is stable and ready for modification.
+
+## Dev Agent Record
+
+### Agent Model Used
+
+Claude Opus 4.6 (1M context)
+
+### Debug Log References
+
+- Verified bmad-method `--custom-content` deploys to `_bmad/custom/` NOT `_bmad/extensions/` — kept manual extension copy (belt-and-suspenders approach per Dev Notes)
+- cli.js call sites unchanged since new params use default destructured options `{} = {}` — backward compatible without modification
+
+### Completion Notes List
+
+- Created `buildBmadArgs(ctx)` function implementing Architecture Decision P2-6, replacing 3 ad-hoc string-concatenation command construction sites
+- `buildBmadArgs()` delegates to existing `getBmadCommand()` for wrapper path resolution (preserving Story 5.1 fix)
+- All 3 callsites (`installBmad`, `updateBmad`, `applyCustomizations` recompile) now use `buildBmadArgs()`
+- Added `{ userName, commLang, docLang, outputFolder }` options object to `installBmad()`, `updateBmad()`, and `applyCustomizations()` with empty-string defaults
+- `--custom-content` automatically included when `lib/bmad-extension/` directory exists
+- ALL string arguments double-quoted for space-in-path safety: `--directory`, `--user-name`, `--communication-language`, `--document-output-language`, `--output-folder`, `--custom-content` (ties to Story 5.6)
+- Input validation added: `buildBmadArgs()` throws clear error on missing `projectRoot` or non-array `modules`
+- Graceful handling of undefined/null `tools` array (defaults to `--tools none`)
+- 31 unit tests covering all parameter combinations, quoting, edge cases, input validation, and function signatures
+- Full regression suite: 148 tests pass, 0 failures
+- Code review findings addressed: H1 (--output-folder quoting), H2 (language flag quoting), M2 (Task 5.2 clarification), M3/M4 (unconditional --custom-content test + edge case), M5 (input validation), L1 (null tools test)
+- M1 (shell injection via execSync) noted as pre-existing pattern — deferred to future wizard story when user-facing params are collected
+
+### File List
+
+- `lib/bmad.js` — Added `buildBmadArgs()`, updated `installBmad()`, `updateBmad()`, `applyCustomizations()` signatures and command construction
+- `test/build-bmad-args.test.js` — New: 22 unit tests for `buildBmadArgs()` and updated function signatures
+- `package.json` — Added `build-bmad-args.test.js` to test script
+- `_bmad-output/implementation-artifacts/sprint-status.yaml` — Status: ready-for-dev → review
+- `_bmad-output/implementation-artifacts/5-5-explicit-parameter-passing.md` — Story file updates (tasks, status, dev record)
+
+## Change Log
+
+- 2026-03-26: Implemented Story 5.5 — replaced 3 ad-hoc command construction sites with single `buildBmadArgs()` function per Architecture Decision P2-6. Added explicit parameter passing for `--user-name`, `--communication-language`, `--document-output-language`, `--output-folder`, and `--custom-content` flags. All string arguments double-quoted for space safety. 31 tests, 0 regressions.
+- 2026-03-26: Addressed code review findings — 2 High, 5 Medium, 1 Low. Fixed inconsistent quoting (H1/H2), added input validation (M5), improved test coverage (M3/M4/L1), clarified Task 5.2 (M2). Shell injection concern (M1) noted for future wizard story.