ma-agents 3.6.2 → 3.9.0

package/_bmad-output/implementation-artifacts/7-1-test-infrastructure-setup.md

@@ -1,144 +0,0 @@
-# Story 7.1: Set Up Test Framework and First Tests for agents.js
-
-Status: ready-for-dev
-
-<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
-
-## Story
-
-As a **developer**,
-I want a test framework configured with initial tests for the agent registry module,
-So that agent configuration changes are verified automatically.
-
-## Acceptance Criteria
-
-1. **Given** Node.js built-in test runner is configured in `package.json`
-   **When** `npm test` is executed
-   **Then** tests run and report results (exit 0 on pass, non-zero on failure)
-
-2. **Given** tests exist for `agents.js`
-   **When** the test suite runs
-   **Then** it verifies:
-   - All 11 agents are registered with required fields (`id`, `name`, `version`, `category`, `description`, `getProjectPath`, `getGlobalPath`, `fileExtension`, `template`, `instructionFiles`)
-   - `getProjectPath()` returns a string containing the agent's expected directory name
-   - `getGlobalPath()` returns a valid path for the current OS
-   - `resourceMap` is defined for agents that need it (currently only `cline`)
-   - No duplicate agent `id` values exist in the registry
-   - `getAgent(id)` returns the correct agent object
-   - `getAllAgents()` returns all 11 agents
-   - `getAgentsByCategory('ide')` returns 7 agents, `getAgentsByCategory('bmad')` returns 4 agents
-
-## Tasks / Subtasks
-
-- [ ] Task 1: Configure Node.js built-in test runner (AC: #1)
-  - [ ] 1.1: Replace the current placeholder test script in `package.json:11` with `node --test tests/`
-  - [ ] 1.2: Verify `node --test` works with the project's minimum Node.js version (`>=16.0.0` per `package.json:33`) — Note: `node --test` requires Node 18+. If minimum version must stay at 16, consider `node --test tests/*.test.js` with a version check
-  - [ ] 1.3: Create `tests/` directory at project root
-  - [ ] 1.4: Run `npm test` — verify it discovers and runs test files (even if empty initially)
-- [ ] Task 2: Write agents.js tests (AC: #2)
-  - [ ] 2.1: Create `tests/agents.test.js`
-  - [ ] 2.2: Test: `getAllAgents()` returns exactly 11 agents
-  - [ ] 2.3: Test: every agent has all required fields (`id`, `name`, `version`, `category`, `description`, `getProjectPath`, `getGlobalPath`, `fileExtension`, `template`, `instructionFiles`)
-  - [ ] 2.4: Test: `getProjectPath()` returns a string for each agent
-  - [ ] 2.5: Test: `getGlobalPath()` returns a string for each agent
-  - [ ] 2.6: Test: no duplicate `id` values across agents
-  - [ ] 2.7: Test: `getAgent('claude-code')` returns agent with `name: 'Claude Code'`
-  - [ ] 2.8: Test: `getAgent('nonexistent')` returns `undefined`
-  - [ ] 2.9: Test: `getAgentsByCategory('ide')` returns 7 agents
-  - [ ] 2.10: Test: `getAgentsByCategory('bmad')` returns 4 agents
-  - [ ] 2.11: Test: `cline` agent has `resourceMap` with `references` and `assets` keys
-  - [ ] 2.12: Test: agents without `resourceMap` don't have the property (or it's undefined)
-  - [ ] 2.13: Test: all `instructionFiles` entries are non-empty strings
-
-## Dev Notes
-
-### Architecture Compliance
-
-- **Test location:** `tests/` directory at project root, mirroring source structure. Co-located tests are not used. [Source: architecture.md#Structure-Patterns]
-- **No new runtime dependencies:** The test runner is built into Node.js. No Jest, Mocha, or Vitest needed. [Source: architecture.md#Anti-Patterns]
-- **Test framework decision:** Architecture recommends Node.js built-in test runner (no dependencies, aligns with minimal approach). [Source: architecture.md#Infrastructure-Deployment]
-
-### Node.js Built-in Test Runner
-
-Use `node:test` module (available since Node 18.x, stable in Node 20+):
-
-```javascript
-const { describe, it } = require('node:test');
-const assert = require('node:assert');
-const { getAgent, getAllAgents, getAgentsByCategory } = require('../lib/agents');
-
-describe('agents registry', () => {
-  it('should have 11 agents', () => {
-    assert.strictEqual(getAllAgents().length, 11);
-  });
-});
-```
-
-Run with: `node --test tests/`
-
-### Node.js Version Consideration
-
-Current `package.json` specifies `"node": ">=16.0.0"`. The built-in test runner requires Node 18+. Options:
-1. **Recommended:** Bump minimum to `>=18.0.0` (Node 16 EOL was September 2023 — well past)
-2. **Alternative:** Keep >=16 but note tests require 18+ (add check in test script)
-
-### Current Test Script
-
-The existing `package.json` test script is a placeholder:
-```json
-"test": "node -e \"const {listSkills,listAgents}=require('./lib/installer'); console.log('Skills:',listSkills().length,'Agents:',listAgents().length)\""
-```
-This should be replaced with the proper test runner command.
-
-### Exported Functions from agents.js
-
-From [agents.js:256-272](lib/agents.js#L256-L272):
-- `getAgent(agentId)` — returns single agent by id
-- `getAllAgents()` — returns full array (11 agents)
-- `getAgentsByCategory(category)` — filtered by 'ide' or 'bmad'
-
-### Agent Registry Schema (from actual code)
-
-Every agent object has these fields (verified from [agents.js:17-253](lib/agents.js#L17-L253)):
-- `id` (string) — unique identifier (e.g., 'claude-code', 'copilot')
-- `name` (string) — display name (e.g., 'Claude Code', 'GitHub Copilot')
-- `version` (string) — semver (e.g., '1.0.0')
-- `category` (string) — 'ide' or 'bmad'
-- `description` (string) — brief description
-- `getProjectPath` (function) — returns project-level skills directory path
-- `getGlobalPath` (function) — returns global/user-level skills directory path
-- `fileExtension` (string) — '.md' for all current agents
-- `template` (string) — 'claude-code', 'cline', or 'generic'
-- `instructionFiles` (array of strings) — instruction file paths
-
-Optional:
-- `resourceMap` (object) — only on `cline` agent (maps 'references' → 'docs', 'assets' → 'templates')
-
-### Critical Guardrails
-
-- **No new npm dependencies** — use Node.js built-in `node:test` and `node:assert` only
-- **Tests must not modify the file system** — agents.js is pure data + functions, no side effects
-- **Do not modify `lib/agents.js`** — tests should validate existing behavior, not change it
-
-### Project Structure Notes
-
-- Files to create: `tests/agents.test.js`
-- Files to modify: `package.json` (update test script, optionally bump engine version)
-- No changes to `lib/` source files
-
-### References
-
-- [Source: _bmad-output/planning-artifacts/epics.md#Epic-7] — Story 7.1 definition
-- [Source: _bmad-output/planning-artifacts/architecture.md#Structure-Patterns] — Tests directory location
-- [Source: _bmad-output/planning-artifacts/architecture.md#Infrastructure-Deployment] — Test framework recommendation
-- [Source: lib/agents.js] — Agent registry (11 agents, 272 lines, 3 exported functions)
-
-## Dev Agent Record
-
-### Agent Model Used
-
-### Debug Log References
-
-### Completion Notes List
-
-### File List

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

@@ -1,132 +0,0 @@
-# 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

@@ -1,119 +0,0 @@
-# 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

@@ -1,162 +0,0 @@
-# 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