ma-agents 3.4.9 → 3.5.1

package/_bmad-output/implementation-artifacts/7-2-installer-pipeline-tests.md

@@ -0,0 +1,132 @@
+# Story 7.2: Add Tests for installer.js Core Operations
+
+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 the installer engine's core operations,
+So that skill installation, manifest management, and MANIFEST.yaml generation are protected against regressions.
+
+## Acceptance Criteria
+
+1. **Given** tests exist for `installer.js`
+   **When** the test suite runs
+   **Then** it verifies:
+   - Skill discovery scans the `skills/` directory and finds all valid skills
+   - Template resolution follows priority chain (agent-specific → generic → SKILL.md)
+   - Manifest read/write operations are atomic (no partial states)
+   - MANIFEST.yaml generation produces valid YAML from installed skills
+   - Additive-only installation does not remove existing agent configurations (NFR5)
+
+2. **Given** a test skill directory is set up in a temp directory
+   **When** install operations are tested
+   **Then** files are written to the temp directory, not actual agent config directories
+
+## Tasks / Subtasks
+
+- [ ] Task 1: Create test fixtures (AC: #2)
+  - [ ] 1.1: Create `tests/fixtures/` directory for test skill data
+  - [ ] 1.2: Create a minimal test skill: `tests/fixtures/test-skill/skill.json` + `SKILL.md`
+  - [ ] 1.3: Create a test skill with templates: `tests/fixtures/test-skill-with-templates/` including `templates/claude-code.md` and `templates/generic.md`
+  - [ ] 1.4: Create a test skill with resources: `tests/fixtures/test-skill-with-resources/` including `references/` and `assets/` directories
+- [ ] Task 2: Test skill discovery functions (AC: #1)
+  - [ ] 2.1: Create `tests/installer.test.js`
+  - [ ] 2.2: Test: `listSkills()` returns an array of skill objects (currently 28 skills)
+  - [ ] 2.3: Test: each skill object has required fields from `skill.json` (name, version, description, category)
+  - [ ] 2.4: Test: `listAgents()` returns the same as `getAllAgents()` from agents.js
+  - [ ] 2.5: Test: `getInstalledSkillInfo()` returns null/undefined for non-installed skills
+- [ ] Task 3: Test manifest operations (AC: #1)
+  - [ ] 3.1: Test: `readManifest()` returns empty manifest for non-existent path
+  - [ ] 3.2: Test: `writeManifest()` creates valid JSON file
+  - [ ] 3.3: Test: `ensureManifest()` creates manifest entry for agent+scope
+  - [ ] 3.4: Test: `getManifestAgents()` returns agent IDs from manifest
+  - [ ] 3.5: Test: manifest write → read roundtrip preserves data
+  - [ ] 3.6: All manifest tests use `os.tmpdir()` temp directory, cleaned up after
+- [ ] Task 4: Test MANIFEST.yaml generation (AC: #1)
+  - [ ] 4.1: Test: `generateSkillsManifest()` produces a file ending in `.yaml`
+  - [ ] 4.2: Test: generated MANIFEST.yaml content includes skill names and metadata
+  - [ ] 4.3: Use temp directory for generation output
+- [ ] Task 5: Test semver comparison (AC: #1)
+  - [ ] 5.1: Test: `compareSemver('1.0.0', '1.0.0')` returns 0
+  - [ ] 5.2: Test: `compareSemver('1.0.0', '2.0.0')` returns -1
+  - [ ] 5.3: Test: `compareSemver('2.0.0', '1.0.0')` returns 1
+  - [ ] 5.4: Test: `compareSemver('1.0.1', '1.0.0')` returns 1
+
+## Dev Notes
+
+### Architecture Compliance
+
+- **Test location:** `tests/installer.test.js` in the tests directory [Source: architecture.md#Structure-Patterns]
+- **Temp directory isolation:** All file-writing tests must use `os.tmpdir()` or `fs.mkdtempSync()`. Never write to actual agent config directories or the project's `skills/` directory during tests. [Source: AC #2]
+- **No mocking the database:** Tests should use real file system operations in temp directories, not mocked fs. [Source: architecture.md — integration test philosophy]
+
+### installer.js Exported Functions
+
+From [installer.js:10-591](lib/installer.js) — 16 functions, key ones for testing:
+
+**Pure/stateless (easy to test):**
+- `listSkills()` (line 178) — scans `skills/` directory, returns array of skill metadata
+- `listAgents()` (line 204) — delegates to agents.js `getAllAgents()`
+- `compareSemver(a, b)` (line 166) — pure comparison function
+- `getPackageVersion()` (line 10) — reads package.json version
+
+**Manifest operations (need temp dir):**
+- `readManifest(installPath)` (line 17) — reads `.ma-agents.json`
+- `writeManifest(installPath, manifest)` (line 29) — writes `.ma-agents.json`
+- `ensureManifest(installPath, agentId, scope)` (line 34) — creates manifest structure
+- `getManifestAgents(manifest)` (line 59) — extracts agent IDs from manifest
+- `getInstalledSkillInfo(installPath, skillId)` (line 67) — reads installed skill version
+
+**File-writing operations (need temp dir + careful isolation):**
+- `generateSkillsManifest(installPath)` (line 75) — generates MANIFEST.yaml
+- `performInstall(skillId, skill, agent, installPath)` (line 210) — copies skill files
+- `installSkill(skillId, agentIds, ...)` (line 278) — full install orchestration
+
+**Note:** `performInstall` and `installSkill` involve complex file operations and agent path resolution. Consider testing these in Story 7.2 only at the unit level (manifest + discovery), deferring full integration install tests if they require too much setup.
+
+### Test Fixture Skill Schema
+
+Minimal `skill.json` for test fixtures:
+```json
+{
+  "name": "test-skill",
+  "version": "1.0.0",
+  "description": "Test skill for automated testing",
+  "category": "testing",
+  "tags": ["test"],
+  "always_load": false
+}
+```
+
+### Critical Guardrails
+
+- **Never write to real agent directories** — all file operations in temp dirs only
+- **Clean up temp dirs after each test** — use `t.after()` or `after()` hooks
+- **No new npm dependencies** — use `node:test`, `node:assert`, `node:fs`, `node:os`, `node:path`
+- **Do not modify `lib/installer.js`** — tests validate existing behavior
+
+### Project Structure Notes
+
+- Files to create: `tests/installer.test.js`, `tests/fixtures/test-skill/` (skill.json + SKILL.md), `tests/fixtures/test-skill-with-templates/`
+- No changes to `lib/` source files
+
+### References
+
+- [Source: _bmad-output/planning-artifacts/epics.md#Epic-7] — Story 7.2 definition
+- [Source: _bmad-output/planning-artifacts/architecture.md#Structure-Patterns] — Test directory structure
+- [Source: lib/installer.js] — Installer module (591 lines, 16 functions)
+- [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/7-3-bmad-pipeline-tests.md

@@ -0,0 +1,119 @@
+# Story 7.3: Add Tests for bmad.js Pipeline Ordering
+
+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 verifying the BMAD pipeline executes stages in strict order,
+So that customization ordering bugs are caught before release.
+
+## Acceptance Criteria
+
+1. **Given** tests exist for `bmad.js`
+   **When** the test suite runs
+   **Then** it verifies:
+   - The 6-stage BMAD pipeline executes in correct order
+   - YAML configs are applied before recompile
+   - Workflows, templates, and agents are applied after recompile
+   - Pipeline failure at any stage prevents subsequent stages from executing
+
+## Tasks / Subtasks
+
+- [ ] Task 1: Analyze bmad.js for testable functions (AC: #1)
+  - [ ] 1.1: Map the 6-stage BMAD pipeline stages in `applyCustomizations()` (line 59)
+  - [ ] 1.2: Identify which functions are exported vs internal
+  - [ ] 1.3: Determine testability — `bmad.js` calls `npx bmad-method install` as a subprocess; tests must NOT trigger real BMAD installs
+  - [ ] 1.4: Decide approach: test internal logic without triggering `child_process.exec` calls, or mock the exec calls
+- [ ] Task 2: Create bmad.js tests (AC: #1)
+  - [ ] 2.1: Create `tests/bmad.test.js`
+  - [ ] 2.2: Test: `isBmadInstalled()` returns false for empty directory (use temp dir)
+  - [ ] 2.3: Test: `isBmadInstalled()` returns true for directory containing `_bmad/` folder
+  - [ ] 2.4: Test: exported functions exist (`installBmad`, `updateBmad`, `applyCustomizations`, `isBmadInstalled`, `registerMilWorkflows`)
+  - [ ] 2.5: Test: `applyCustomizations()` processes config files in correct order (YAML configs before workflows/templates/agents)
+  - [ ] 2.6: Test: customization file discovery — verify `fs.readdirSync` on `lib/bmad-customizations/` returns expected files
+  - [ ] 2.7: Test: `lib/bmad-workflows/` directory exists and contains expected workflow content
+  - [ ] 2.8: Test: `lib/mil498-templates/` directory exists and contains template files
+- [ ] Task 3: Test pipeline ordering logic (AC: #1)
+  - [ ] 3.1: Verify the `applyCustomizations()` function processes in this order:
+    1. YAML config files (`.customize.yaml`)
+    2. Recompile trigger
+    3. Workflow customizations
+    4. Template customizations
+    5. Agent customizations
+  - [ ] 3.2: Create a spy/tracker to verify execution order without triggering real file copies
+  - [ ] 3.3: Test that the function signature matches expected parameters: `(projectRoot, modules, tools, selectedAgentIds)`
+
+## Dev Notes
+
+### Architecture Compliance
+
+- **Test location:** `tests/bmad.test.js` [Source: architecture.md#Structure-Patterns]
+- **Pipeline ordering is critical:** The 6-stage BMAD pipeline (NFR8) has strict ordering requirements. YAML configs MUST be applied before recompile, and workflows/templates/agents MUST be applied after. [Source: architecture.md#Pipeline-Architecture]
+- **No real BMAD installs:** Tests must NOT call `npx bmad-method install` — this would modify the actual project's `_bmad/` directory. [Source: test isolation principle]
+
+### bmad.js Module Structure
+
+From [bmad.js:1-250](lib/bmad.js) — 250 lines, 5 exported functions:
+
+```
+isBmadInstalled(projectRoot)           — line 9  — checks for _bmad/ directory
+installBmad(modules, tools, projectRoot) — line 13 — runs npx bmad-method install
+updateBmad(modules, tools, projectRoot)  — line 36 — runs npx bmad-method update
+applyCustomizations(projectRoot, ...)    — line 59 — 6-stage pipeline
+registerMilWorkflows(projectRoot)        — line 170 — MIL-498 workflow registration
+```
+
+### Testing Challenge: Subprocess Calls
+
+`installBmad()` and `updateBmad()` spawn child processes via `exec('npx bmad-method install ...')`. These functions are **not suitable for unit testing** without mocking `child_process`.
+
+**Approach options:**
+1. **Test only pure logic:** Focus on `isBmadInstalled()`, file discovery in `applyCustomizations()`, and function signatures. Skip subprocess-dependent functions.
+2. **Mock child_process:** Intercept `exec` calls to verify command construction without executing. More complex but validates the pipeline.
+3. **Hybrid:** Test what we can without mocking, defer subprocess testing to integration tests.
+
+**Recommended:** Option 1 (pure logic) for this story. Focus on `isBmadInstalled()`, customization file discovery, and pipeline stage ordering verification.
+
+### Pipeline Stage Ordering in applyCustomizations()
+
+The function at line 59 applies customizations in this order:
+1. Config YAML files → `lib/bmad-customizations/` configs
+2. Recompile step → triggers BMAD recompile
+3. Workflows → `lib/bmad-workflows/` content
+4. Templates → `lib/mil498-templates/` content
+5. Agent files → agent customize.yaml files
+
+Verify ordering by checking the function's code flow, not by executing it.
+
+### Critical Guardrails
+
+- **Never trigger real BMAD installs** during tests — no `npx bmad-method` execution
+- **Use temp directories** for `isBmadInstalled()` tests
+- **No new npm dependencies** — use `node:test` and `node:assert` only
+- **Do not modify `lib/bmad.js`** — tests validate existing behavior
+
+### Project Structure Notes
+
+- Files to create: `tests/bmad.test.js`
+- No changes to `lib/` source files
+
+### References
+
+- [Source: _bmad-output/planning-artifacts/epics.md#Epic-7] — Story 7.3 definition
+- [Source: _bmad-output/planning-artifacts/architecture.md#Pipeline-Architecture] — BMAD 6-stage pipeline, NFR8
+- [Source: lib/bmad.js] — BMAD module (250 lines, 5 exported functions)
+- [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/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.