ma-agents 3.4.8 → 3.5.0

package/_bmad-output/implementation-artifacts/7-4-cli-command-routing-tests.md

@@ -0,0 +1,162 @@
+# Story 7.4: Add Tests for cli.js Command Routing
+
+Status: ready-for-dev
+
+<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
+<!-- Dependency: Story 7-1 must be completed first (test framework setup) -->
+
+## Story
+
+As a **developer**,
+I want tests covering CLI command parsing and routing,
+So that command-line argument handling is verified automatically.
+
+## Acceptance Criteria
+
+1. **Given** tests exist for `cli.js`
+   **When** the test suite runs
+   **Then** it verifies:
+   - Known commands (install, list, status, uninstall) route correctly
+   - Unknown commands produce helpful error messages
+   - Flag parsing (`--yes`, `--force`, `--agent`) extracts values correctly
+   - Help output is displayed for `--help` flag
+   - Version output is displayed for `--version` flag
+
+## Tasks / Subtasks
+
+- [ ] Task 1: Analyze cli.js testability (AC: #1)
+  - [ ] 1.1: Map the command routing in `main()` function (line 523)
+  - [ ] 1.2: Identify `parseFlags(args)` function (line 107) — this is a pure function, directly testable
+  - [ ] 1.3: Identify which functions can be tested without triggering interactive prompts or real installs
+  - [ ] 1.4: Note: `cli.js` is the `bin` entry point — it calls `main()` on require. Tests must NOT require cli.js directly or it will execute. Import specific functions or test via subprocess.
+- [ ] Task 2: Test flag parsing (AC: #1)
+  - [ ] 2.1: Create `tests/cli.test.js`
+  - [ ] 2.2: **Challenge:** `parseFlags()` is not exported — it's internal to cli.js. Options:
+    - Option A: Export `parseFlags` from cli.js for testing (minor, safe change)
+    - Option B: Test via subprocess: `node bin/cli.js --help` and verify output
+    - Option C: Extract `parseFlags` to a shared utility (over-engineering for this story)
+  - [ ] 2.3: If Option A: Test `parseFlags(['--yes'])` returns `{ yes: true }`
+  - [ ] 2.4: If Option A: Test `parseFlags(['--force'])` returns `{ force: true }`
+  - [ ] 2.5: If Option A: Test `parseFlags(['--agent', 'claude-code'])` returns `{ agent: 'claude-code' }`
+  - [ ] 2.6: If Option A: Test `parseFlags([])` returns empty/default flags
+- [ ] Task 3: Test CLI commands via subprocess (AC: #1)
+  - [ ] 3.1: Test: `node bin/cli.js --help` exits 0 and outputs usage info
+  - [ ] 3.2: Test: `node bin/cli.js --version` exits 0 and outputs version matching `package.json` version
+  - [ ] 3.3: Test: `node bin/cli.js list` exits 0 and outputs skill/agent listings
+  - [ ] 3.4: Test: `node bin/cli.js list --skills` exits 0 and outputs skill names
+  - [ ] 3.5: Test: `node bin/cli.js list --agents` exits 0 and outputs agent names
+  - [ ] 3.6: Test: `node bin/cli.js unknowncommand` exits non-zero or outputs help/error
+  - [ ] 3.7: Use `child_process.execSync` or `child_process.exec` for subprocess testing
+- [ ] Task 4: Test help and version output content (AC: #1)
+  - [ ] 4.1: Test: help output contains key command names (install, list, status, uninstall)
+  - [ ] 4.2: Test: version output matches `require('../package.json').version`
+
+## Dev Notes
+
+### Architecture Compliance
+
+- **Test location:** `tests/cli.test.js` [Source: architecture.md#Structure-Patterns]
+- **CLI entry point hazard:** `bin/cli.js` calls `main()` at the bottom of the file. Requiring it directly would trigger the CLI. Tests must either:
+  1. Test via subprocess (`child_process.exec('node bin/cli.js ...')`)
+  2. Or export specific functions and guard `main()` behind `require.main === module` check
+- **No real installs:** CLI tests must not trigger `install` or `uninstall` operations
+
+### cli.js Module Structure
+
+From [cli.js:1-565](bin/cli.js) — 565 lines, key functions:
+
+**Display functions (no side effects beyond console output):**
+- `showHelp()` (line 13) — prints usage info
+- `showSkills()` (line 42) — lists skills
+- `showAgents()` (line 51) — lists agents
+- `showStatus(args)` (line 70) — shows install status
+
+**Parsing functions (pure logic, most testable):**
+- `parseFlags(args)` (line 107) — extracts --yes, --force, --agent, --skill, --scope, --path flags
+
+**Command handlers (orchestrate operations, harder to test):**
+- `handleInstall(args)` (line 425) — install command handler
+- `handleUninstall(args)` (line 453) — uninstall command handler
+- `installWizard(...)` (line 130) — interactive install flow
+- `interactiveMode()` (line 480) — interactive menu
+- `main()` (line 523) — entry point, routes commands
+
+### parseFlags() Function Detail
+
+From [cli.js:107-127](bin/cli.js#L107-L127):
+```javascript
+function parseFlags(args) {
+  // Parses: --yes, --force, --agent <name>, --skill <name>, --scope <scope>, --path <path>
+  // Returns object with extracted values
+}
+```
+
+This is the best candidate for direct unit testing if exported.
+
+### Subprocess Testing Pattern
+
+```javascript
+const { execSync } = require('node:child_process');
+const { describe, it } = require('node:test');
+const assert = require('node:assert');
+
+describe('CLI commands', () => {
+  it('--help should exit 0 and show usage', () => {
+    const output = execSync('node bin/cli.js --help', { encoding: 'utf-8' });
+    assert.ok(output.includes('Usage'));
+  });
+
+  it('--version should show package version', () => {
+    const output = execSync('node bin/cli.js --version', { encoding: 'utf-8' });
+    const { version } = require('../package.json');
+    assert.ok(output.includes(version));
+  });
+});
+```
+
+### Minimal Source Change Option
+
+To test `parseFlags()` directly, a small change to `cli.js` may be needed:
+
+```javascript
+// At bottom of cli.js, replace direct main() call:
+if (require.main === module) {
+  main();
+}
+
+// And export testable functions:
+module.exports = { parseFlags };
+```
+
+This is a minimal, safe change that enables direct testing while preserving CLI behavior. Discuss with reviewer if this is acceptable or if subprocess-only testing is preferred.
+
+### Critical Guardrails
+
+- **Never trigger real installs** — only test non-destructive commands (list, help, version, status)
+- **No interactive prompts in tests** — avoid commands that trigger `prompts` library
+- **subprocess tests must have timeout** — prevent hanging tests
+- **No new npm dependencies** — use `node:test`, `node:assert`, `node:child_process`
+- **Minimal changes to `bin/cli.js`** — only `require.main` guard and optional exports if needed
+
+### Project Structure Notes
+
+- Files to create: `tests/cli.test.js`
+- Files to potentially modify: `bin/cli.js` (add `require.main` guard + export parseFlags — minimal change)
+- No changes to `lib/` source files
+
+### References
+
+- [Source: _bmad-output/planning-artifacts/epics.md#Epic-7] — Story 7.4 definition
+- [Source: _bmad-output/planning-artifacts/architecture.md#Structure-Patterns] — Test directory structure
+- [Source: bin/cli.js] — CLI module (565 lines, 10 functions, entry point)
+- [Source: _bmad-output/implementation-artifacts/7-1-test-infrastructure-setup.md] — Prerequisite story
+
+## Dev Agent Record
+
+### Agent Model Used
+
+### Debug Log References
+
+### Completion Notes List
+
+### File List

package/_bmad-output/implementation-artifacts/deferred-work.md

@@ -0,0 +1,9 @@
+# Deferred Work
+
+## Deferred from: code review of 17-9-unified-sprint-status-schema (2026-04-03)
+
+- sprint-status.yaml still uses old flat `development_status` format — migration is Story 17.23
+- `generated` field in sprint-status.yaml is bare date, not ISO-8601 datetime — will be reformatted by Story 17.15 bootstrap
+- No `schema_version` metadata field — can be added in a future story if schema evolution is needed
+- Concurrent modification has no locking guidance — skills run serially in current architecture
+- `correct-course` referenced in schema Section 4.6 but not in skill integration map — informational reference only

package/_bmad-output/implementation-artifacts/done/1-1-ci-cd-yes-flag.md

@@ -0,0 +1,200 @@
+# Story 1.1: Add --yes Flag for Non-Interactive Skill Installation
+
+Status: review
+
+<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
+
+## Story
+
+As a **DevOps engineer**,
+I want to run `npx ma-agents install --yes` to skip all interactive prompts,
+So that I can automate skill installation in CI/CD pipelines without human intervention.
+
+## Acceptance Criteria
+
+1. **Given** the CLI is invoked with `--yes` flag
+   **When** the install command executes
+   **Then** all interactive prompts (skill selection, agent selection, confirmations) are bypassed with default selections
+   **And** the installation completes without requiring stdin input
+   **And** exit code 0 is returned on success, non-zero on failure
+
+2. **Given** the CLI is invoked with `--yes --force` flags together
+   **When** the install command executes
+   **Then** all interactive prompts are skipped with default selections (same as `--yes` alone)
+   **And** existing skill files are overwritten without version comparison (the `--force` behavior)
+   **Note:** `--yes` controls prompt skipping; `--force` controls file overwrite. They are orthogonal.
+
+3. **Given** the CLI is invoked with `--yes` and a specific agent target (e.g., `--agent claude-code`)
+   **When** the install command executes
+   **Then** only the specified agent is targeted without prompting for agent selection
+   **And** all skills are installed to that agent without skill selection prompts
+
+## Tasks / Subtasks
+
+- [x] Task 1: Add `--yes` and `--agent` flag parsing to `parseFlags()` (AC: #1, #2, #3)
+  - [x] 1.1: Add `yesFlag` boolean extraction in `parseFlags()` function (search: `function parseFlags`). Same pattern as existing `forceFlag`.
+  - [x] 1.2: Add `--agent <name>` extraction in `parseFlags()`. Pattern: same as `--path` — extract next positional arg after `--agent` as the agent name. Return as `agentFlag`.
+  - [x] 1.3: Filter `--yes` and `--agent <name>` from positional args (same filter pattern as `--global` and `--force`)
+  - [x] 1.4: Validate `--agent` value: if `--agent` is present but no name follows, print `Error: --agent requires an agent name` / `Hint: Run "list" to see available agents` and exit 1
+  - [x] 1.5: Add `--yes` and `--agent <name>` to help text (search: `console.log.*Usage`)
+- [x] Task 2: Update `installWizard()` to bypass prompts when `--yes` is active (AC: #1)
+  - [x] 2.1: Accept `yesFlag` parameter in `installWizard()` signature (search: `async function installWizard`)
+  - [x] 2.2: Skip existing installation check prompt (search: `Existing installation detected`) — default to `'reinstall'` (clean slate, then install all). This avoids the `isUpdate` path which re-triggers skill selection prompts.
+  - [x] 2.3: Skip skill selection prompt (search: `install all available skills or choose`) — default to ALL skills. **Important:** when `yesFlag` is true, also skip when `isUpdate` is true — the `isUpdate` OR condition must not re-trigger prompts.
+  - [x] 2.4: Skip IDE agent selection prompt (search: `Select AI Coding Assistants`) — default to ALL detected IDE agents. If zero IDE agents detected, set to empty array (not an error — BMAD agents may still be selected).
+  - [x] 2.5: Skip BMAD agent selection prompt (search: `Select BMAD Method Agents`) — default to ALL BMAD agents
+  - [x] 2.6: After agent selection, if total `selectedAgentIds` is zero, print `Error: No agents detected` / `Hint: Ensure at least one supported IDE is present` and exit 1. This is expected CI/CD behavior — fail fast with a clear message rather than silently succeeding with nothing installed.
+  - [x] 2.7: Skip scope selection prompt (search: `Installation scope`) — default to `'project'` scope. Note: if `--global` or `--path` was already provided by the user, those take precedence and this prompt is already skipped by existing logic.
+  - [x] 2.8: Skip BMAD install/update prompts (search: `BMAD-METHOD not detected` / `BMAD-METHOD installation detected`) — default to YES. **Caution:** the BMAD tools filter (search: `['claude-code', 'cursor', 'cline', 'gemini', 'antigravity']`) is hardcoded; agents outside this list will not receive BMAD customizations. This is existing behavior, not a new concern, but log a warning if `selectedAgentIds` contains agents not in the filter list.
+  - [x] 2.9: Skip final confirmation prompt (search: `Proceed with installation`) — proceed immediately
+- [x] Task 3: Update `handleInstall()` to pass `yesFlag` and `agentFlag` through call chain (AC: #1, #2, #3)
+  - [x] 3.1: Extract `yesFlag` and `agentFlag` from parsed flags in `handleInstall()` (search: `async function handleInstall`)
+  - [x] 3.2: When `agentFlag` is present, validate it against known agents (call `listAgents()` and check). If invalid, print `Error: Unknown agent '<name>'` / `Hint: Run "list" to see available agents` and exit 1.
+  - [x] 3.3: Pass `yesFlag` to `installWizard()` call
+  - [x] 3.4: When `agentFlag` is present, pass it as `preselectedAgents: [agentFlag]` to `installWizard()`, which skips agent selection entirely (existing behavior when `preselectedAgents` is non-empty)
+  - [x] 3.5: Pass `yes: yesFlag` in options to `installSkill()` calls
+- [x] Task 4: Update `installSkill()` to honor `--yes` for upgrade/downgrade prompts (AC: #1)
+  - [x] 4.1: Accept `yes` in options destructuring (search: `async function installSkill`, then the `const { force` destructure)
+  - [x] 4.2: When `yes === true` and skill is already installed and `force` is false: skip upgrade/downgrade/same-version decision prompts (search: `What would you like to do?` inside `installSkill`). Default action: `'update'` (install the package version). This does NOT force file overwrites — it simply auto-selects "update" instead of prompting.
+  - [x] 4.3: When `yes === true`, pre-set `batchState.globalAction = 'update'` so all remaining skills in the batch also auto-update without prompts (search: `batchState`).
+  - [x] 4.4: Guard against accidental prompt execution: if `yes === true` and any `prompts()` call returns `undefined` (which happens when stdin is closed/piped), treat it as a fatal error — print `Error: Unexpected interactive prompt in non-interactive mode` and exit 1. This catches missed bypass paths.
+- [x] Task 5: Ensure proper exit codes (AC: #1)
+  - [x] 5.1: Verify `process.exit(0)` on successful non-interactive completion
+  - [x] 5.2: Verify `process.exit(1)` on any failure (no skills found, no agents detected, invalid `--agent` name, install errors)
+  - [x] 5.3: Ensure no dangling promises or unhandled rejections that could prevent clean exit
+- [x] Task 6: Automated tests (AC: #1, #2, #3)
+  - [x] 6.1: Unit test `parseFlags()` with `--yes`, `--yes --force`, `--yes --agent claude-code`, `--yes --agent` (missing name)
+  - [x] 6.2: Unit test `installWizard()` with `yesFlag=true`: mock `prompts` and assert it is NEVER called. Verify all defaults are applied correctly.
+  - [x] 6.3: Unit test `installSkill()` with `yes=true`: verify prompts are skipped and default action is `'update'`
+  - [x] 6.4: Integration test: run `npx ma-agents install --yes` with stdin piped from `/dev/null` and assert exit code 0, no stdin reads, and expected output
+  - [x] 6.5: Integration test: run `npx ma-agents install --yes --agent invalid-agent-name` and assert exit code 1 with error message
+- [ ] Task 7: Manual smoke testing
+  - [ ] 7.1: `npx ma-agents install --yes` — installs all skills to all detected agents, project scope
+  - [ ] 7.2: `npx ma-agents install --yes --force` — same as above but overwrites existing files
+  - [ ] 7.3: `npx ma-agents install --yes --agent claude-code` — installs all skills to Claude Code only
+  - [ ] 7.4: `npx ma-agents install --yes --global` — installs all skills globally
+  - [ ] 7.5: `echo '' | npx ma-agents install --yes` — verify zero stdin dependency
+
+## Dev Notes
+
+### Architecture Compliance
+
+- **Module boundaries:** All CLI argument parsing stays in `bin/cli.js`. The `--yes` flag is parsed there and passed as an option to `lib/installer.js`. installer.js NEVER parses CLI args directly — it receives options objects. This is the established pattern with `--force`.
+- **No new dependencies:** The `prompts` library is already used. When `--yes` is active, prompts are simply NOT called — no need for a mock or alternative prompting library.
+- **Code style:** Plain JavaScript, camelCase for variables/functions, no classes. Follow exact patterns from existing `forceFlag` implementation.
+
+### Key Implementation Pattern
+
+The `--force` flag provides the exact model to follow:
+1. **Parsed in `parseFlags()`** (search: `function parseFlags`) — boolean extraction from args array
+2. **Passed through call chain** — `handleInstall()` → `installWizard()` / `installSkill()`
+3. **Consumed in functions** — conditionally skip prompts based on flag value
+
+The `--yes` flag follows this IDENTICAL pattern but covers a broader scope:
+- `--force`: skips file-overwrite guards (the `if (installed && !force)` gate in `installSkill`)
+- `--yes`: skips ALL interactive prompts (wizard + upgrade/downgrade), selecting sensible defaults
+- `--yes --force`: skips ALL prompts AND forces file overwrites — the two flags are **orthogonal**
+
+### Flag Semantics: `--yes` vs `--force`
+
+These flags operate on different axes and MUST NOT be conflated:
+
+| Flag | What it controls | Effect in `installSkill()` |
+|------|-----------------|---------------------------|
+| `--yes` | Prompt skipping | When a skill is already installed, auto-selects `'update'` action instead of prompting. Does NOT bypass version comparison — the version check still runs, it just auto-decides. |
+| `--force` | File overwrite | Bypasses the entire `if (installed && !force)` block. Skips version comparison entirely and proceeds directly to file copy/overwrite. |
+| `--yes --force` | Both | `--force` takes precedence in `installSkill()` (the `!force` gate means the prompt block is never entered, so `--yes` has no additional effect there). In `installWizard()`, `--yes` skips wizard prompts while `--force` is passed through for file operations. |
+
+### Default Selections When --yes is Active
+
+| Prompt | Default (--yes) | Code anchor (search string) |
+|--------|----------------|---------------------------|
+| Existing installation action | `'reinstall'` (clean slate + install all) | `Existing installation detected` |
+| Skill selection | ALL skills | `install all available skills or choose` |
+| IDE agent selection | ALL detected IDE agents | `Select AI Coding Assistants` |
+| BMAD agent selection | ALL BMAD agents | `Select BMAD Method Agents` |
+| Scope | `'project'` (unless `--global` or `--path`) | `Installation scope` |
+| BMAD install/update | YES | `BMAD-METHOD not detected` / `BMAD-METHOD installation detected` |
+| Final confirmation | YES (proceed) | `Proceed with installation` |
+| Upgrade/downgrade decision | `'update'` (install package version) | `What would you like to do?` inside `installSkill` |
+
+**Why `'reinstall'` for existing installation:** The `'update'` action sets `isUpdate = true`, which re-triggers the skill selection prompt (the guard is `selectedSkillIds.length === 0 || isUpdate`). Using `'reinstall'` avoids this interaction — it clears existing installs and proceeds to install all skills cleanly, which is the expected CI/CD behavior.
+
+### Critical Guardrails
+
+- **Never add TypeScript, build steps, or new dependencies** [Source: architecture.md#Anti-Patterns]
+- **Use `path.join()` for all file paths** — no string concatenation [Source: architecture.md#Enforcement-Guidelines]
+- **Preserve module boundaries** — CLI parsing in cli.js, install logic in installer.js [Source: architecture.md#Module-Boundaries]
+- **Console output format:** plain text, chalk colors (green=success, yellow=warning, red=error), no emoji [Source: architecture.md#Format-Patterns]
+- **Error format:** `Error: <what>` then `  Hint: <how to fix>` [Source: architecture.md#Format-Patterns]
+- **Defensive prompt guard:** In `--yes` mode, if any `prompts()` call executes and returns `undefined` (which happens when stdin is closed/piped from `/dev/null`), this indicates a missed bypass. Treat as fatal: print error and exit 1. This prevents silent success-exit on incomplete operations.
+
+### Interaction with --agent Flag
+
+The `--agent <name>` flag is NOT currently parsed by `parseFlags()`. This story adds it as a first-class flag (Task 1.2) because AC #3 requires it for CI/CD usage.
+
+**Parsing pattern:** Same as `--path` — extract the next positional arg after `--agent` as the agent name, splice both from positional args.
+
+**Validation:** `handleInstall()` validates the agent name against `listAgents()` before passing to `installWizard()`. Invalid names produce `Error: Unknown agent '<name>'` / `Hint: Run "list" to see available agents` and exit 1.
+
+**Interaction with `--yes`:** When `--agent` is present, it is passed as `preselectedAgents`, which already skips agent selection in the existing wizard logic. `--yes` is not required for `--agent` to work, but they combine naturally.
+
+### Batch State Consideration
+
+The installer has a `batchState` pattern (search: `batchState` in `installSkill`) for "apply decision to all remaining" during multi-skill installs. When `--yes` is active, pre-set `batchState.globalAction = 'update'` before the skill install loop. This ensures all skills auto-update without prompts, using the existing batch mechanism rather than bypassing prompts individually (cleaner, fewer code paths to maintain).
+
+### BMAD Tools Filter Limitation
+
+The BMAD integration code (search: `['claude-code', 'cursor', 'cline', 'gemini', 'antigravity']`) hardcodes a filter for which agents receive BMAD customizations. In `--yes` mode, if `selectedAgentIds` includes agents not in this list, those agents will not receive BMAD customizations. This is existing behavior, not introduced by this story, but in `--yes` mode a warning should be logged: `Warning: Agent '<name>' is not supported for BMAD customizations`.
+
+### Project Structure Notes
+
+- Files to modify: `bin/cli.js`, `lib/installer.js`
+- Test files to create: `test/yes-flag.test.js` (or add to existing test file if one exists)
+- No directory structure changes
+- Alignment with unified project structure: confirmed — both files are established modules in the 4-module architecture
+
+### References
+
+- [Source: _bmad-output/planning-artifacts/epics.md#Epic-1] — Epic 1 story definition and acceptance criteria
+- [Source: _bmad-output/planning-artifacts/prd.md#FR6] — FR6: Non-interactive CI/CD mode requirement
+- [Source: _bmad-output/planning-artifacts/prd.md#NFR9] — NFR9: Cross-platform identical results
+- [Source: _bmad-output/planning-artifacts/architecture.md#Pipeline-Architecture] — Install pipeline 5 stages
+- [Source: _bmad-output/planning-artifacts/architecture.md#Implementation-Patterns] — Naming, structure, format, process patterns
+- [Source: _bmad-output/planning-artifacts/architecture.md#Module-Boundaries] — cli.js/installer.js/agents.js/bmad.js boundaries
+- [Source: bin/cli.js `function parseFlags`] — Current parseFlags() implementation
+- [Source: bin/cli.js `async function installWizard`] — Current installWizard() with all prompt locations
+- [Source: lib/installer.js `async function installSkill`] — Current installSkill() with force flag pattern
+
+## Dev Agent Record
+
+### Agent Model Used
+
+claude-sonnet-4-6
+
+### Debug Log References
+
+None — implementation proceeded cleanly without debugging issues.
+
+### Completion Notes List
+
+- Added `yesFlag` and `agentFlag` to `parseFlags()` with filtering from positional args; validated `--agent` presence requires a name argument.
+- Updated `installWizard()` with 5th parameter `yesFlag=false`; all 8 interactive prompts are bypassed with sensible defaults when `yesFlag=true`: reinstall (Step 0), all skills (Step 1), all agents (Step 2), project scope (Step 3), BMAD auto-install/update (Step 3.5), skip confirmation (Step 4).
+- Updated `handleInstall()` to extract `yesFlag`/`agentFlag`, validate `agentFlag` against `listAgents()`, and pass both through to wizard and direct-install paths.
+- Updated `installSkill()` to accept `yes` option; pre-sets `batchState.globalAction = 'update'` at the top of the function (before path group iteration) so all skills in the batch auto-update; added `undefined`-guard after each `prompts()` call as defensive check.
+- Added `require.main === module` guard in `cli.js` and exported `parseFlags` to enable unit testing without triggering main().
+- Created `test/yes-flag.test.js` with 9 tests covering all ACs: 5 parseFlags unit tests, 2 integration tests for error exits, 1 batchState pre-set unit test, 1 integration test for full `--yes` install.
+- Updated `package.json` test script to run `node test/yes-flag.test.js`.
+- All 9 automated tests pass. Task 7 (manual smoke tests) left for user to verify.
+
+### File List
+
+- bin/cli.js (modified)
+- lib/installer.js (modified)
+- test/yes-flag.test.js (created)
+- package.json (modified — test script)
+- _bmad-output/implementation-artifacts/1-1-ci-cd-yes-flag.md (this file)
+
+## Change Log
+
+- 2026-03-16: Implemented `--yes` and `--agent` flags for non-interactive CI/CD mode. Modified `parseFlags()`, `installWizard()`, `handleInstall()` in `bin/cli.js` and `installSkill()` in `lib/installer.js`. Created `test/yes-flag.test.js` with 9 passing automated tests. All ACs #1, #2, #3 satisfied.

package/_bmad-output/implementation-artifacts/done/10-1-ensure-bmad-output-not-gitignored.md

@@ -0,0 +1,172 @@
+# Story 10.1: Ensure _bmad-output Is Not Gitignored
+
+Status: done
+
+<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
+
+## Story
+
+As a **Chief Architect**,
+I want the installer to remove _bmad-output from .gitignore if present and never add it,
+So that planning artifacts are tracked as version-controlled project knowledge.
+
+## Acceptance Criteria
+
+1. **Given** project with _bmad-output in .gitignore, **When** installer runs (install/update), **Then** _bmad-output line removed, **And** the console displays exactly: `_bmad-output is now tracked as project knowledge (not gitignored)`
+2. **Given** project with no _bmad-output in .gitignore, **When** installer runs, **Then** .gitignore not modified for this concern (no write call is made)
+3. **Given** no .gitignore exists, **When** installer runs, **Then** no .gitignore created for this purpose and no error thrown
+4. **Given** installer creates/updates .gitignore for other entries, **When** it writes, **Then** _bmad-output never included in the written content
+
+## Tasks / Subtasks
+
+- [ ] Verify chalk is already a project dependency (`package.json`) before using chalk.green(); add import/require at the top of installer.js if not already present (AC: #1)
+- [ ] Create ensureBmadOutputTracked(projectRoot) function in lib/installer.js (AC: #1, #2, #3)
+  - [ ] Attempt to read .gitignore with `fs.readFileSync(path.join(projectRoot, '.gitignore'), 'utf-8')` inside a `try/catch`; on `ENOENT` (or any error), return early — do NOT use `existsSync` pre-check followed by `readFileSync` (avoids TOCTOU race condition) (AC: #3)
+  - [ ] Split content on `/\r?\n/` to handle both Unix (LF) and Windows (CRLF) line endings — never split on `'\n'` alone (AC: #1, Windows compat)
+  - [ ] Trim each line before pattern comparison (handles trailing whitespace) (AC: #1)
+  - [ ] Scan for lines matching _bmad-output variations after trimming: `_bmad-output`, `_bmad-output/`, `/_bmad-output`, `/_bmad-output/`
+  - [ ] Remove matching lines; reconstruct file content preserving original line endings (join with `'\n'` is acceptable as normalized output)
+  - [ ] Write back only if at least one line was removed (AC: #2)
+  - [ ] Print `chalk.green('_bmad-output is now tracked as project knowledge (not gitignored)')` when lines are removed (AC: #1)
+- [ ] Integrate ensureBmadOutputTracked() into install pipeline (AC: #1)
+  - [ ] Call after skill installation or during manifest update stage
+- [ ] Audit existing codebase for any code that adds _bmad-output to .gitignore (AC: #4)
+  - [ ] Check lib/installer.js for any .gitignore write logic that includes _bmad-output
+  - [ ] Check lib/bmad.js for any .gitignore write logic that includes _bmad-output
+  - [ ] Remove any such logic if found
+- [ ] Remove _bmad-output/ from the ma-agents project's own .gitignore (AC: #4)
+
+### Tests
+
+- [ ] Test AC1 — removal and message:
+  - [ ] Fixture: .gitignore containing `_bmad-output/` among other entries
+  - [ ] Assert: `_bmad-output/` line removed from written content
+  - [ ] Assert: `writeFileSync` (or equivalent) WAS called once
+  - [ ] Assert: console output contains the exact string `_bmad-output is now tracked as project knowledge (not gitignored)`
+- [ ] Test AC2 — no-op when already clean:
+  - [ ] Fixture: .gitignore with no _bmad-output entry
+  - [ ] Assert: `writeFileSync` (or equivalent) was NOT called (use sinon spy or jest mock)
+- [ ] Test AC3 — missing .gitignore:
+  - [ ] Fixture: project directory with no .gitignore file
+  - [ ] Assert: no error thrown, no .gitignore created
+- [ ] Test AC4 — installer write paths never include _bmad-output:
+  - [ ] Spy on all .gitignore write call sites in lib/installer.js and lib/bmad.js
+  - [ ] Assert: none of the written content strings include `_bmad-output`
+  - [ ] This test acts as a regression guard — future code changes that reintroduce the pattern will fail this test
+- [ ] Test — Windows CRLF compatibility:
+  - [ ] Fixture: .gitignore with `_bmad-output/\r\n` (Windows line endings)
+  - [ ] Assert: line is correctly detected and removed (match does not fail due to `\r`)
+- [ ] Test — idempotency:
+  - [ ] Run ensureBmadOutputTracked() on a project where _bmad-output was already removed in a prior run
+  - [ ] Assert: `writeFileSync` is NOT called on the second run (no spurious file churn)
+- [ ] Test — own .gitignore cleanup:
+  - [ ] Assert: the ma-agents project's own .gitignore does not contain `_bmad-output` (grep assertion on the file)
+
+## Dev Notes
+
+### Architecture Compliance
+- FR58/FR59: _bmad-output is project knowledge and must be version-controlled.
+- Use `fs.readFileSync(path, 'utf-8')` — always pass the `'utf-8'` encoding option. Without it, `readFileSync` returns a Buffer; calling `.split()` on a Buffer throws a TypeError in some Node versions and produces unexpected behavior in others.
+- Console output uses `chalk.green()` per established console output patterns in the codebase. Verify chalk import style matches the project's module system (CJS `require` vs ESM `import`) — chalk v5+ is ESM-only.
+- `path.join()` for all file path construction.
+
+### TOCTOU Fix — CRITICAL
+Do NOT use the pattern:
+```js
+if (fs.existsSync(filePath)) {
+  const content = fs.readFileSync(filePath, 'utf-8');
+  ...
+}
+```
+The file can be deleted between `existsSync` and `readFileSync`. Use instead:
+```js
+try {
+  const content = fs.readFileSync(filePath, 'utf-8');
+  // proceed
+} catch (err) {
+  if (err.code === 'ENOENT') return; // file doesn't exist — no-op
+  throw err; // unexpected error — re-throw
+}
+```
+
+### Windows Line Ending Fix — CRITICAL
+Do NOT split on `'\n'` alone. Use:
+```js
+const lines = content.split(/\r?\n/);
+```
+Then trim each line before comparison:
+```js
+const trimmed = line.trim();
+if (BMAD_OUTPUT_PATTERNS.includes(trimmed)) { ... }
+```
+This handles both `_bmad-output\r` (Windows CRLF) and `_bmad-output` (Unix LF).
+
+### Pattern List
+```js
+const BMAD_OUTPUT_PATTERNS = ['_bmad-output', '_bmad-output/', '/_bmad-output', '/_bmad-output/'];
+```
+Note: commented-out lines (e.g., `# _bmad-output`) and glob variants (e.g., `_bmad-output/**`) are out of scope for this story. The four listed patterns cover the common cases written by IDEs and developers.
+
+### Write Guard (AC2)
+Only write back if lines were actually removed:
+```js
+const filtered = lines.filter(line => !BMAD_OUTPUT_PATTERNS.includes(line.trim()));
+if (filtered.length === lines.length) return; // nothing removed — do not write
+fs.writeFileSync(filePath, filtered.join('\n'), 'utf-8');
+```
+
+### Exact Message (AC1)
+The chalk output must produce exactly this text (the chalk color wrapping is fine, but the string content must match):
+```
+_bmad-output is now tracked as project knowledge (not gitignored)
+```
+Test assertions must verify this exact string, not just "something was logged."
+
+### Critical Guardrails
+- Do NOT use `existsSync` before `readFileSync` — use try/catch with `ENOENT` check
+- Do NOT use `readFileSync` without `'utf-8'` encoding
+- Do NOT split on `'\n'` alone — always use `/\r?\n/`
+- Do NOT create a .gitignore file if one does not exist
+- Do NOT remove other entries from .gitignore — only _bmad-output variations
+- Do NOT skip the AC2 write-guard test — assert the write function was NOT called
+
+### Project Structure Notes
+- Modify: `lib/installer.js` — add ensureBmadOutputTracked() function and call it in install pipeline
+- Modify: `.gitignore` (project root) — remove `_bmad-output/` entry
+- Audit: `lib/bmad.js` — check for any .gitignore write logic referencing _bmad-output
+
+### References
+- [Source: lib/installer.js — install pipeline for integration point]
+- [Source: .gitignore — current _bmad-output/ entry to remove]
+- [Source: lib/bmad.js — audit for .gitignore write logic]
+
+## Dev Agent Record
+
+### Agent Model Used
+claude-sonnet-4-6
+
+### Debug Log References
+None — implementation was straightforward with no debugging required.
+
+### Completion Notes List
+- ✅ Added `BMAD_OUTPUT_PATTERNS` constant and `ensureBmadOutputTracked(projectRoot)` function to `lib/installer.js` after `writeManifest()`
+- ✅ Uses try/catch with ENOENT check (no TOCTOU race), splits on `/\r?\n/`, trims lines before comparison, writes back only if lines removed
+- ✅ Called `ensureBmadOutputTracked(installPath)` immediately after `writeManifest(installPath, manifest)` in `installSkill()`
+- ✅ Exported `ensureBmadOutputTracked` in `module.exports`
+- ✅ Removed commented `_bmad-output/` line from project `.gitignore` (line 16)
+- ✅ Created `test/bmad-output-policy.test.js` with 6 Story 10-1 tests (AC1–AC3, CRLF, idempotency, own .gitignore) plus 5 relocated Story 10-2 README tests
+- ✅ Removed Story 10-2 test block from `test/yes-flag.test.js`
+- ✅ Strengthened discoverable assertion in relocated test (counts H2s before section, asserts ≤ 3)
+- ✅ All 11 tests in `test/bmad-output-policy.test.js` pass
+
+### File List
+- `lib/installer.js` (modified — added `ensureBmadOutputTracked()`, call in `installSkill()`, exported)
+- `.gitignore` (modified — removed commented `_bmad-output/` line)
+- `test/bmad-output-policy.test.js` (created — 11 tests for Stories 10-1 and 10-2)
+- `test/yes-flag.test.js` (modified — removed Story 10-2 test block)
+- `_bmad-output/implementation-artifacts/10-1-ensure-bmad-output-not-gitignored.md` (modified — status → done)
+- `_bmad-output/implementation-artifacts/10-2-document-bmad-output-policy.md` (modified — status → done)
+- `_bmad-output/implementation-artifacts/sprint-status.yaml` (modified — 10-2 → done)
+
+### Change Log
+- 2026-03-18: Implemented Story 10-1 — ensureBmadOutputTracked() in lib/installer.js; also completed Story 10-2 closure (test relocation, status updates)

package/_bmad-output/implementation-artifacts/done/10-2-document-bmad-output-policy.md

@@ -0,0 +1,102 @@
+# Story 10.2: Document _bmad-output Policy in README and Installation Guidance
+
+Status: done
+
+depends-on: 10-1-ensure-bmad-output-not-gitignored
+
+<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
+
+## Story
+
+As a **Chief Architect**,
+I want the _bmad-output folder policy documented in the README and installation guidance,
+So that developers understand why _bmad-output is version-controlled and do not add it back to .gitignore.
+
+## Acceptance Criteria
+
+1. **Given** the project README, **When** a developer reads it, **Then** it contains a dedicated section explaining that `_bmad-output/` is intentionally tracked in version control as project knowledge, **And** the section explains what the folder contains (planning artifacts: PRDs, architecture, epics, stories, sprint plans), **And** the section explains why it is tracked (team alignment, AI context continuity, project history).
+2. **Given** the installation or getting-started documentation, **When** a developer sets up the tool, **Then** the guidance explicitly states that `_bmad-output/` must not be added to `.gitignore` and explains that the installer will remove it if found.
+3. **Given** the README section on `_bmad-output`, **When** a developer's IDE or tooling suggests adding it to `.gitignore`, **Then** the documentation gives them the language to confidently decline (i.e., the rationale is clear and actionable).
+
+## Tasks / Subtasks
+
+- [x] Add `_bmad-output/` policy section to README.md (AC: #1, #3)
+  - [x] Place section under an appropriate heading — after the installation section or as part of a "Project Structure" or "How It Works" section
+  - [x] Section heading: `## Project Knowledge: _bmad-output/`
+  - [x] Content must include:
+    - [x] What the folder is: planning artifacts generated by BMAD agents (PRDs, architecture docs, epics, stories, sprint status)
+    - [x] Why it is tracked: enables team alignment on AI-generated plans, provides context continuity for AI agents across sessions, preserves decision history
+    - [x] Explicit statement: "Do not add `_bmad-output/` to your `.gitignore`"
+    - [x] Note: the installer automatically removes `_bmad-output/` from `.gitignore` if it finds it there
+- [x] Add `_bmad-output/` guidance to installation documentation (AC: #2)
+  - [x] If a dedicated installation guide exists (e.g., INSTALL.md, docs/getting-started.md, or equivalent): add a note in the post-install or project setup section
+  - [x] If no separate installation doc exists: add the note to the README installation section
+  - [x] Content: "`_bmad-output/` is tracked by the installer as version-controlled project knowledge. Do not add it to `.gitignore`. If it is present in `.gitignore`, the installer will remove it automatically."
+- [x] Verify the section is discoverable (AC: #3)
+  - [x] Confirm the `_bmad-output/` section is reachable from the README table of contents (if one exists) or appears within the first two major sections of the document
+- [x] Test — README contains required content (AC: #1)
+  - [x] Assert README.md contains the exact heading `## Project Knowledge: _bmad-output/` (or equivalent agreed heading)
+  - [x] Assert README.md contains the phrase "Do not add `_bmad-output/` to your `.gitignore`"
+  - [x] Assert README.md mentions at least one reason for tracking (e.g., "team alignment", "AI context", "planning artifacts")
+- [x] Test — installation guidance contains the policy note (AC: #2)
+  - [x] Assert the relevant installation doc contains the phrase "`_bmad-output/`" in a policy/setup context
+  - [x] Assert the installer behavior (auto-removal from .gitignore) is mentioned
+
+## Dev Notes
+
+### Scope
+This is a documentation-only story. No code changes to `lib/installer.js`, `lib/agents.js`, or any other source file. The deliverables are markdown edits to `README.md` and optionally one installation documentation file.
+
+### Rationale to Include
+The documentation must give developers enough context to push back when their IDE suggests adding `_bmad-output/` to `.gitignore`. The key points:
+1. **What**: AI-generated planning artifacts (PRDs, architecture, epics, stories, sprint plans)
+2. **Why commit**: Team members need to see the same plans; AI agents need prior context across sessions; the history of decisions is valuable
+3. **Installer behavior**: The tool actively removes this entry from `.gitignore` — documenting this prevents confusion when developers notice their `.gitignore` was modified
+
+### Section Placement
+Prefer placing the section near the existing description of how the tool works — not buried in a troubleshooting FAQ. Developers should encounter it during normal onboarding, not only when something goes wrong.
+
+### Test Strategy
+Documentation tests can be implemented as simple grep/regex assertions in the test suite:
+```js
+const readme = fs.readFileSync('README.md', 'utf-8');
+assert(readme.includes('_bmad-output'));
+assert(readme.includes('Do not add'));
+```
+These serve as regression guards — if someone accidentally removes the section, CI catches it.
+
+### Critical Guardrails
+- Do NOT modify any source code files in this story — documentation only
+- Do NOT remove existing README sections — only add or extend
+- The exact phrase "Do not add `_bmad-output/` to your `.gitignore`" (or semantically equivalent) must appear in the written content
+
+### Project Structure Notes
+- Modify: `README.md` — add `_bmad-output/` policy section
+- Modify (if exists): installation guide or getting-started doc — add policy note
+- No source code changes
+
+### References
+- [FR59: _bmad-output policy documented in README and installation guidance]
+- [FR58: _bmad-output not added to .gitignore by installer — covered in Story 10.1]
+- [Story 10.1 — ensureBmadOutputTracked() behavior that this story documents]
+
+## Dev Agent Record
+
+### Agent Model Used
+claude-sonnet-4-6
+
+### Debug Log References
+None — documentation-only story.
+
+### Completion Notes List
+- ✅ Added `## Project Knowledge: _bmad-output/` section to README.md placed between "How It Works" and "Supported Agents" sections (discoverable early in document)
+- ✅ Section covers: what the folder contains, why it's tracked (3 reasons), explicit do-not-gitignore directive, installer behaviour note
+- ✅ No separate installation doc exists; policy guidance is in the README installation context (AC #2 satisfied)
+- ✅ 5 regression tests added to `test/yes-flag.test.js` — all pass
+
+### File List
+- `README.md` (modified — added `## Project Knowledge: _bmad-output/` section)
+- `test/yes-flag.test.js` (modified — added Story 10.2 documentation regression tests)
+
+### Change Log
+- 2026-03-18: Implemented Story 10.2 — documented _bmad-output/ policy in README.md with regression tests