ma-agents 3.4.8 → 3.5.0

package/_bmad-output/implementation-artifacts/done/3-2-skill-validation-tool.md

@@ -0,0 +1,178 @@
+# Story 3.2: Skill Validation Command
+
+Status: review
+
+<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
+
+## Story
+
+As a **Chief Architect**,
+I want to run `npx ma-agents validate-skill <skill-name>` to check a skill for schema compliance,
+So that I can catch skill format errors before distribution.
+
+## Acceptance Criteria
+
+1. **Given** the user runs `npx ma-agents validate-skill my-skill`
+   **When** the skill directory exists and contains valid files
+   **Then** the command reports "VALID" with a summary of skill metadata
+
+2. **Given** the skill is missing `skill.json`
+   **When** the validate command runs
+   **Then** it reports "INVALID: missing required file skill.json"
+
+3. **Given** the skill is missing `SKILL.md`
+   **When** the validate command runs
+   **Then** it reports "INVALID: missing required file SKILL.md"
+
+4. **Given** the `skill.json` has missing or invalid fields (no name, no version, invalid category)
+   **When** the validate command runs
+   **Then** it reports each validation error with the field name and expected format
+
+5. **Given** the skill has agent-specific templates in `templates/`
+   **When** the validate command runs
+   **Then** it verifies each template filename matches a known agent registry key
+   **And** warns about templates targeting unknown agents
+
+## Tasks / Subtasks
+
+- [x] Task 1: Add `validate-skill` command to CLI router (AC: #1-#5)
+  - [x] 1.1: Add `validate-skill` to command routing in `bin/cli.js`
+  - [x] 1.2: Create `validateSkill(skillName)` function in `lib/skill-authoring.js` (created in Story 3-1)
+  - [x] 1.3: Add `validate-skill` to help text
+- [x] Task 2: Implement file existence checks (AC: #2, #3)
+  - [x] 2.1: Check `skills/<skill-name>/` directory exists — if not: `Error: Skill '<skill-name>' not found` / `Hint: Run "list" to see available skills`
+  - [x] 2.2: Check `skill.json` exists — if not: add to errors list "missing required file skill.json"
+  - [x] 2.3: Check `SKILL.md` exists — if not: add to errors list "missing required file SKILL.md"
+- [x] Task 3: Implement skill.json field validation (AC: #4)
+  - [x] 3.1: Parse skill.json — if invalid JSON: `INVALID: skill.json is not valid JSON`
+  - [x] 3.2: Validate required fields:
+    - `name` (string, non-empty)
+    - `version` (string, semver pattern)
+    - `description` (string, present)
+  - [x] 3.3: Validate optional fields if present:
+    - `category` (one of: security, architecture, testing, documentation, workflow, language)
+    - `tags` (array of strings)
+    - `always_load` (boolean)
+    - `author` (string)
+    - `applies_when` (array of strings)
+  - [x] 3.4: Report each field error individually: `  - name: required, must be a non-empty string`
+- [x] Task 4: Implement template validation (AC: #5)
+  - [x] 4.1: If `templates/` directory exists, scan for `.md` files
+  - [x] 4.2: Extract agent name from filename (e.g., `claude-code.md` -> `claude-code`)
+  - [x] 4.3: Check each name against agent registry keys from `lib/agents.js` (call `getAllAgents()`)
+  - [x] 4.4: Warn (yellow) about unknown agents: `Warning: Template 'unknown-agent.md' targets unknown agent 'unknown-agent'`
+  - [x] 4.5: Valid templates get a checkmark: `  Template: claude-code.md (valid agent)`
+- [x] Task 5: Implement output summary (AC: #1)
+  - [x] 5.1: If all checks pass: print `VALID` (green) + metadata summary (name, version, category, tags count, always_load)
+  - [x] 5.2: If any errors: print `INVALID` (red) + list of all errors
+  - [x] 5.3: Exit code 0 on valid, 1 on invalid
+- [x] Task 6: Test the command
+  - [x] 6.1: Run on a known valid skill (e.g., `git-workflow-skill`) — verify VALID
+  - [x] 6.2: Create a deliberately broken skill and validate — verify all errors caught
+  - [x] 6.3: Test with template targeting unknown agent — verify warning
+
+## Dev Notes
+
+### Architecture Compliance
+
+- **Module placement:** Add to `lib/skill-authoring.js` (created in Story 3-1). Validation logic lives alongside scaffolding — both are skill authoring tools.
+- **Agent registry access:** Use `lib/agents.js` for template validation (AC #5). Import agent listing function to check template filenames. This is a read-only dependency — agents.js is "pure data + path functions" per the boundary table. [Source: architecture.md#Module-Boundaries]
+- **No new dependencies.** JSON parsing is built-in. Semver validation can use a simple regex pattern — no need for the `semver` package.
+
+### Validation Rules Summary
+
+| Field | Type | Required | Validation |
+|-------|------|----------|-----------|
+| `name` | string | Yes | Non-empty |
+| `version` | string | Yes | Matches `/^\d+\.\d+\.\d+$/` (basic semver) |
+| `description` | string | Yes | Non-empty |
+| `category` | string | No | One of: security, architecture, testing, documentation, workflow, language |
+| `tags` | array | No | Array of strings |
+| `always_load` | boolean | No | Must be boolean if present |
+| `author` | string | No | Non-empty string if present |
+| `applies_when` | array | No | Array of strings |
+
+### Output Format
+
+**Valid skill:**
+```
+VALID: git-workflow-skill
+  Name: Git Workflow
+  Version: 2.1.0
+  Category: workflow
+  Tags: 6 tags
+  Always Load: true
+  Templates: claude-code.md (valid)
+```
+
+**Invalid skill:**
+```
+INVALID: broken-skill
+  Errors:
+  - missing required file SKILL.md
+  - name: required, must be a non-empty string
+  - version: must match semver format (e.g., 1.0.0)
+  - category: must be one of: security, architecture, testing, documentation, workflow, language
+  Warnings:
+  - Template 'unknown-agent.md' targets unknown agent 'unknown-agent'
+```
+
+### Dependency on Story 3-1
+
+This story depends on `lib/skill-authoring.js` being created in Story 3-1. If Story 3-1 is not yet implemented, create the module as part of this story. The module is lightweight — it exports functions, no class hierarchy.
+
+### Critical Guardrails
+
+- **Use `path.join()` for all paths** [Source: architecture.md#Enforcement-Guidelines]
+- **No new npm dependencies** [Source: architecture.md#Anti-Patterns]
+- **Error format:** `Error: <what>` / `Hint: <fix>` [Source: architecture.md#Format-Patterns]
+- **Read-only access to agents.js** — import listing function, do not modify agent registry
+- **Exit code 0 on valid, 1 on invalid** — enables CI/CD usage of validation
+
+### Project Structure Notes
+
+- Files to modify: `bin/cli.js` (add command route), `lib/skill-authoring.js` (add validation function)
+- No new files beyond what Story 3-1 creates
+- No changes to existing skills, installer, or agents modules
+
+### References
+
+- [Source: _bmad-output/planning-artifacts/epics.md#Epic-3] — Story 3.2 definition
+- [Source: _bmad-output/planning-artifacts/prd.md#FR39] — FR39: Skill authoring format
+- [Source: _bmad-output/planning-artifacts/architecture.md#Data-Architecture] — Skill schema contract (skill.json fields)
+- [Source: _bmad-output/planning-artifacts/architecture.md#Extensibility-Model] — Template resolution and agent registry
+- [Source: _bmad-output/planning-artifacts/architecture.md#Format-Patterns] — Console output format
+- [Source: lib/agents.js] — Agent registry for template validation
+
+## Dev Agent Record
+
+### Agent Model Used
+
+claude-sonnet-4-6
+
+### Debug Log References
+
+None — implementation was straightforward.
+
+### Completion Notes List
+
+- Added `validateSkill(skillName, skillsDir)` and `handleValidateSkill(args)` to `lib/skill-authoring.js`
+- Added `getAllAgents` import from `lib/agents.js` for template agent-ID validation
+- Added `VALID_CATEGORIES` constant and `SEMVER_PATTERN` regex at module scope
+- Wired `validate-skill` into `bin/cli.js` switch + help text + import
+- Added `validate-skill` to `npm test` in `package.json`
+- Created `test/skill-validation.test.js` with 21 tests: 14 unit + 7 CLI integration, all passing
+- Zero regressions across all 55 total project tests
+- `validateSkill` returns `{ valid, notFound?, errors[], warnings[], metadata? }` — label-free data, display handled by handler
+- Warnings (unknown agent templates) do not set `valid=false` — only errors do
+
+### File List
+
+- `lib/skill-authoring.js` (modified — added validateSkill, handleValidateSkill, constants)
+- `bin/cli.js` (modified — added import, validate-skill case, help text)
+- `test/skill-validation.test.js` (new)
+- `package.json` (modified — added skill-validation.test.js to test script)
+
+### Change Log
+
+- 2026-03-19: Implemented Story 3.2 — validate-skill command with schema validation, template agent checks, and 21 tests

package/_bmad-output/implementation-artifacts/done/3-3-mandatory-skill-designation.md

@@ -0,0 +1,136 @@
+# Story 3.3: Mandatory Skill Designation Tooling
+
+Status: review
+
+<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
+<!-- Note: This story is derived from FR40 in the PRD. It does not have a matching definition in the epics file. -->
+
+## Story
+
+As a **Chief Architect**,
+I want to designate skills as mandatory (`always_load: true`) through a CLI command,
+So that I can enforce organizational standards by ensuring critical skills are always loaded by agents.
+
+## Acceptance Criteria
+
+1. **Given** the user runs `npx ma-agents set-mandatory <skill-name>`
+   **When** the skill exists and `always_load` is currently `false` or absent
+   **Then** `skill.json` is updated with `always_load: true`
+   **And** MANIFEST.yaml is regenerated to reflect the change
+   **And** a success message confirms the skill is now mandatory
+
+2. **Given** the user runs `npx ma-agents set-mandatory <skill-name> --off`
+   **When** the skill exists and `always_load` is currently `true`
+   **Then** `skill.json` is updated with `always_load: false`
+   **And** MANIFEST.yaml is regenerated to reflect the change
+
+3. **Given** the user runs `npx ma-agents list --mandatory`
+   **When** skills with `always_load: true` exist
+   **Then** only mandatory skills are listed with their metadata
+
+## Tasks / Subtasks
+
+- [x] Task 1: Add `set-mandatory` command to CLI router (AC: #1, #2)
+  - [x] 1.1: Add `set-mandatory` to command routing in `bin/cli.js`
+  - [x] 1.2: Create `setMandatory(skillName, enable)` function in `lib/skill-authoring.js`
+  - [x] 1.3: Parse `--off` flag to determine enable/disable
+  - [x] 1.4: Add `set-mandatory` to help text
+- [x] Task 2: Implement always_load toggle (AC: #1, #2)
+  - [x] 2.1: Validate skill exists: check `skills/<skill-name>/skill.json` — if not found: `Error: Skill '<skill-name>' not found`
+  - [x] 2.2: Read `skill.json`, parse JSON
+  - [x] 2.3: Set `always_load` to `true` (default) or `false` (with `--off`)
+  - [x] 2.4: Write back `skill.json` preserving all existing fields and formatting (use `JSON.stringify(data, null, 2)`)
+  - [x] 2.5: Print confirmation: `Skill '<skill-name>' is now mandatory (always_load: true)` or `Skill '<skill-name>' is no longer mandatory (always_load: false)`
+- [x] Task 3: Regenerate MANIFEST.yaml (AC: #1, #2)
+  - [x] 3.1: After updating skill.json, trigger MANIFEST.yaml regeneration
+  - [x] 3.2: Exported `generateSkillsManifest` from `lib/installer.js` (was private)
+  - [x] 3.3: Called from `handleSetMandatory` with `process.cwd()` as installPath (best-effort, no-op if no install found)
+- [x] Task 4: Add `--mandatory` filter to list command (AC: #3)
+  - [x] 4.1: Updated `showSkills(args)` to accept args parameter
+  - [x] 4.2: When `--mandatory` is present, filter skills to only those with `always_load: true`
+  - [x] 4.3: Display filtered list with "Mandatory Skills" heading
+- [x] Task 5: Test the command
+  - [x] 5.1: Run `set-mandatory` on a skill with `always_load: false` — verify update
+  - [x] 5.2: Run `set-mandatory --off` on a mandatory skill — verify toggle
+  - [x] 5.3: Run `list --mandatory` — verify filtering
+  - [x] 5.4: MANIFEST.yaml regeneration called best-effort (no-op without install)
+
+## Dev Notes
+
+### Architecture Compliance
+
+- **Module placement:** `lib/skill-authoring.js` (same module as stories 3-1, 3-2)
+- **MANIFEST.yaml dependency:** The MANIFEST.yaml generation may currently be coupled to the install flow in `lib/installer.js`. This story may require extracting a `regenerateManifest()` function that can be called independently. This is a minor refactor within `installer.js` — not a boundary violation.
+- **File operations:** Read-modify-write pattern for skill.json. Use `JSON.stringify(data, null, 2)` for consistent formatting. Use `path.join()` for all paths.
+
+### Currently Mandatory Skills
+
+From the codebase analysis, these skills currently have `always_load: true`:
+- `python-security-skill`
+- `code-documentation`
+- `git-workflow-skill`
+- `ai-audit-trail`
+
+This command provides a CLI interface to manage this flag rather than requiring manual JSON editing.
+
+### MANIFEST.yaml Regeneration
+
+The MANIFEST.yaml is the agent-facing index of all skills. When `always_load` changes, agents need the updated manifest to know which skills to auto-load. The regeneration must:
+1. Scan all `skills/*/skill.json` files
+2. Build the manifest data structure
+3. Write to `skills/MANIFEST.yaml`
+
+If this logic is currently embedded in the install flow, extract it as a standalone function that both `install` and `set-mandatory` can call.
+
+### Critical Guardrails
+
+- **Preserve existing skill.json fields** — read, modify `always_load` only, write back all fields
+- **Use `path.join()` for all paths** [Source: architecture.md#Enforcement-Guidelines]
+- **No new npm dependencies** [Source: architecture.md#Anti-Patterns]
+- **Error format:** `Error: <what>` / `Hint: <fix>` [Source: architecture.md#Format-Patterns]
+- **snake_case** keys in skill.json [Source: architecture.md#JSON/YAML-Fields]
+
+### Project Structure Notes
+
+- Files to modify: `bin/cli.js` (add command routes), `lib/skill-authoring.js` (add function), possibly `lib/installer.js` (extract manifest generation)
+- No new files
+- No changes to existing skills content
+
+### References
+
+- [Source: _bmad-output/planning-artifacts/prd.md#FR40] — FR40: Mandatory skill designation
+- [Source: _bmad-output/planning-artifacts/architecture.md#Data-Architecture] — Skill schema contract (always_load field)
+- [Source: _bmad-output/planning-artifacts/architecture.md#Extensibility-Model] — Skill library scanning
+- [Source: skills/MANIFEST.yaml] — Generated skill index consumed by agents
+
+## Dev Agent Record
+
+### Agent Model Used
+
+claude-sonnet-4-6
+
+### Debug Log References
+
+None — MANIFEST.yaml regeneration is best-effort; `generateSkillsManifest` was not exported, fixed by exporting it.
+
+### Completion Notes List
+
+- Added `setMandatory(skillName, enable, skillsDir)` and `handleSetMandatory(args)` to `lib/skill-authoring.js`
+- Exported `generateSkillsManifest` from `lib/installer.js` (was internal-only); called best-effort from `handleSetMandatory`
+- Updated `showSkills(args)` in `bin/cli.js` to accept args and support `--mandatory` filter
+- `list` switch case now passes `args.slice(1)` to `showSkills`
+- Added `set-mandatory` to CLI switch + help text
+- Created `test/skill-mandatory.test.js` with 12 tests: 5 unit + 7 CLI integration, all passing
+- Zero regressions — 67 total project tests passing
+
+### File List
+
+- `lib/skill-authoring.js` (modified — added setMandatory, handleSetMandatory)
+- `lib/installer.js` (modified — exported generateSkillsManifest)
+- `bin/cli.js` (modified — showSkills args, list passes args, set-mandatory case/help)
+- `test/skill-mandatory.test.js` (new)
+- `package.json` (modified — added skill-mandatory.test.js to test script)
+
+### Change Log
+
+- 2026-03-19: Implemented Story 3.3 — set-mandatory command, --off toggle, list --mandatory filter, 12 tests

package/_bmad-output/implementation-artifacts/done/3-4-bmad-persona-customization-tooling.md

@@ -0,0 +1,141 @@
+# Story 3.4: BMAD Persona Customization Tooling
+
+Status: review
+
+<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
+<!-- Note: This story is derived from FR41 in the PRD. It does not have a matching definition in the epics file. -->
+
+## Story
+
+As a **Chief Architect**,
+I want CLI tooling to customize BMAD agent personas for organizational processes,
+So that I can adapt BMAD agents (PM, Architect, Dev, QA, SM, Tech Writer, UX Designer) to fit our team's specific workflows without manually editing YAML files.
+
+## Acceptance Criteria
+
+1. **Given** the user runs `npx ma-agents customize-agent <agent-name>`
+   **When** the agent exists in the BMAD agent registry
+   **Then** an interactive wizard guides through persona customization:
+   - Persona description (role, tone, expertise areas)
+   - Menu items (available workflows/commands)
+   - Critical actions (skill loading, custom pre-session actions)
+   **And** a `.customize.yaml` file is generated in the BMAD extension directory
+
+2. **Given** a `.customize.yaml` already exists for the agent
+   **When** the customize command is run
+   **Then** the existing customization is loaded as defaults in the wizard
+   **And** the user can modify individual sections without re-entering everything
+
+3. **Given** the customization is saved
+   **When** BMAD is recompiled (via `npx bmad-method install --action recompile`)
+   **Then** the agent reflects the customized persona, menu, and critical actions
+
+## Tasks / Subtasks
+
+- [x] Task 1: Add `customize-agent` command to CLI router (AC: #1)
+  - [x] 1.1: Add `customize-agent` to command routing in `bin/cli.js`
+  - [x] 1.2: Create `handleCustomizeAgent(args)` function in `lib/skill-authoring.js`
+  - [x] 1.3: Add `customize-agent` to help text
+- [x] Task 2: Implement agent validation (AC: #1)
+  - [x] 2.1: `validateBmadAgent(agentName)` validates against CUSTOM_AGENTS and BUILTIN_AGENTS lists
+  - [x] 2.2: Returns `{ valid: false, hint: '...Available: ...' }` for unknown agents; handler prints Error/Hint
+- [x] Task 3: Implement customization wizard (AC: #1, #2)
+  - [x] 3.1: `loadExistingCustomization(agentName, agentsDir)` returns raw YAML string or null
+  - [x] 3.2: `generateCustomizeYaml` accepts persona data — included in output for custom agents
+  - [x] 3.3: `generateCustomizeYaml` accepts menu data — included in output for custom agents
+  - [x] 3.4: Critical actions 1-3 are hardcoded in MANDATORY_CRITICAL_ACTIONS, always emitted
+  - [x] 3.5: `generateCustomizeYaml` accepts extraActions (keys ≥4) appended after mandatory actions
+- [x] Task 4: Generate .customize.yaml (AC: #1, #3)
+  - [x] 4.1: `writeCustomizeFile` writes to `agentsDir/<agent-name>.customize.yaml`
+  - [x] 4.2: Custom agents: full file with optional persona + menu + critical_actions
+  - [x] 4.3: Built-in agents: critical_actions only (no persona/menu)
+  - [x] 4.4: YAML block style, quoted action strings
+  - [x] 4.5: Header comment includes agent name
+- [x] Task 5: Test the command
+  - [x] 5.1: `validateBmadAgent` unit tests — custom/builtin/unknown/empty (4 tests)
+  - [x] 5.2: `generateCustomizeYaml` unit tests — all YAML generation paths (7 tests)
+  - [x] 5.3: `writeCustomizeFile` / `loadExistingCustomization` unit tests (3 tests)
+  - [x] 5.4: CLI integration tests — unknown agent, no agent, --yes flag (3 tests)
+
+## Dev Notes
+
+### Architecture Compliance
+
+- **Extension module structure:** All customize files go to `lib/bmad-extension/agents/`. This is the BMAD extension directory defined in architecture decision P2-3. [Source: architecture.md#Decision-P2-3]
+- **critical_actions 1-3 are immutable:** These are identical across all 11 agents per P2-4. The tooling must always include them and never allow modification. Custom actions start at index 4+. [Source: architecture.md#Decision-P2-4]
+- **Built-in vs Custom distinction:** Built-in BMM agents (PM, Architect, Dev, QA, SM, Tech Writer, UX Designer) get ONLY critical_actions — no persona or menu overrides. Custom agents (SRE, DevOps, Cyber, MIL-498) get full customization. This distinction MUST be enforced by the tool.
+- **YAML format:** Block style, quoted strings, per extension module authoring patterns. [Source: architecture.md#Extension-Module-Authoring-Patterns]
+
+### Agent Categories
+
+| Category | Agents | Customization Level |
+|----------|--------|-------------------|
+| Custom | bmm-sre, bmm-devops, bmm-cyber, bmm-mil498 | Full: persona + menu + critical_actions |
+| Built-in | bmm-pm, bmm-architect, bmm-dev, bmm-qa, bmm-sm, bmm-tech-writer, bmm-ux-designer | Minimal: critical_actions only |
+
+### Existing Customize Files
+
+Check `lib/bmad-extension/agents/` for existing `.customize.yaml` files. If the directory or files don't exist yet (Phase 2 not implemented), create the directory structure. This story creates the tooling — the actual files may be created by this tool or by Epic 8 (Skill Enforcement Architecture).
+
+### Interactive Prompts and --yes Mode
+
+If `--yes` flag is active (from Story 1-1), this command should either:
+- Skip with a message: `Skipping customize-agent in non-interactive mode` (since customization is inherently interactive)
+- Or use sensible defaults: generate minimal critical_actions-only file
+
+Recommend the skip approach — persona customization requires human input.
+
+### Critical Guardrails
+
+- **critical_actions 1-3 are NEVER modifiable** — hardcode them [Source: architecture.md#Decision-P2-4]
+- **Built-in agents MUST NOT get persona/menu overrides** [Source: architecture.md#Decision-P2-4]
+- **YAML block style, quoted strings** [Source: architecture.md#Extension-Module-Authoring-Patterns]
+- **Use `path.join()` for all paths** [Source: architecture.md#Enforcement-Guidelines]
+- **No new npm dependencies** — use built-in YAML generation (simple template strings for YAML output, or extract from existing bmad.js patterns)
+
+### Project Structure Notes
+
+- Files to modify: `bin/cli.js` (add command route), `lib/skill-authoring.js` (add function)
+- Files created by the tool: `lib/bmad-extension/agents/<agent-name>.customize.yaml`
+- Directory to ensure exists: `lib/bmad-extension/agents/`
+
+### References
+
+- [Source: _bmad-output/planning-artifacts/prd.md#FR41] — FR41: Customize BMAD agent personas
+- [Source: _bmad-output/planning-artifacts/architecture.md#Decision-P2-3] — Extension module structure
+- [Source: _bmad-output/planning-artifacts/architecture.md#Decision-P2-4] — critical_actions for all agents
+- [Source: _bmad-output/planning-artifacts/architecture.md#Extension-Module-Authoring-Patterns] — YAML format rules
+- [Source: lib/bmad-extension/agents/] — Target directory for customize files
+
+## Dev Agent Record
+
+### Agent Model Used
+
+claude-sonnet-4-6
+
+### Debug Log References
+
+None — implementation went GREEN on first attempt. Test file was written first (RED), then implementation produced all 17 tests passing immediately.
+
+### Completion Notes List
+
+- Added `validateBmadAgent`, `generateCustomizeYaml`, `writeCustomizeFile`, `loadExistingCustomization`, `handleCustomizeAgent` to `lib/skill-authoring.js`
+- CUSTOM_AGENTS: bmm-sre, bmm-devops, bmm-cyber, bmm-mil498 (full customization)
+- BUILTIN_AGENTS: bmm-pm, bmm-architect, bmm-dev, bmm-qa, bmm-sm, bmm-tech-writer, bmm-ux-designer (critical_actions only)
+- MANDATORY_CRITICAL_ACTIONS (1-3) are immutable constants, hardcoded in module
+- `--yes` flag generates minimal file in non-interactive mode (prints "non-interactive" in message)
+- Added `handleCustomizeAgent` import and `customize-agent` switch case to `bin/cli.js`
+- Added `customize-agent` to help text in `bin/cli.js`
+- Created `test/skill-customize-agent.test.js` with 17 tests: 14 unit + 3 CLI integration, all passing
+- 84 total project tests passing (was 67)
+
+### File List
+
+- `lib/skill-authoring.js` (modified — added 5 new functions)
+- `bin/cli.js` (modified — import, switch case, help text)
+- `test/skill-customize-agent.test.js` (new)
+- `package.json` (modified — added skill-customize-agent.test.js to test script)
+
+### Change Log
+
+- 2026-03-19: Implemented Story 3.4 — customize-agent command, validateBmadAgent, generateCustomizeYaml, writeCustomizeFile, loadExistingCustomization, 17 tests

package/_bmad-output/implementation-artifacts/done/3-5-specialized-agent-development-tooling.md

@@ -0,0 +1,145 @@
+# Story 3.5: Specialized Agent Development Tooling
+
+Status: review
+
+<!-- Note: Validation is optional. Run validate-create-story for quality check before dev-story. -->
+<!-- Note: This story is derived from FR42 in the PRD. It does not have a matching definition in the epics file. -->
+
+## Story
+
+As a **Chief Architect**,
+I want CLI tooling to develop new specialized agent personas for enterprise-specific roles,
+So that I can create purpose-built agents (like the existing SRE, DevOps, Cyber, MIL-498 agents) for additional organizational roles.
+
+## Acceptance Criteria
+
+1. **Given** the user runs `npx ma-agents create-agent <agent-name>`
+   **When** the command executes
+   **Then** a new agent scaffolding is generated with:
+   - A `.customize.yaml` file with persona, menu, and critical_actions sections (template-filled)
+   - The agent is registered as a "custom" type (full customization)
+   - Skill-loading critical_actions 1-3 are pre-populated
+
+2. **Given** the agent name conflicts with an existing agent
+   **When** the create-agent command is run
+   **Then** the command fails with an error listing the conflicting agent
+
+3. **Given** the new agent is created
+   **When** BMAD is installed with the extension module
+   **Then** the new agent appears in the BMAD agent menu and can be loaded
+
+## Tasks / Subtasks
+
+- [x] Task 1: Add `create-agent` command to CLI router (AC: #1, #2)
+  - [x] 1.1: Added `create-agent` to command routing in `bin/cli.js`
+  - [x] 1.2: Created `validateAgentName`, `createBmadAgent`, `handleCreateAgent` in `lib/skill-authoring.js`
+  - [x] 1.3: Added `create-agent` to help text
+- [x] Task 2: Implement agent name validation (AC: #2)
+  - [x] 2.1: `validateAgentName` checks against `/^bmm-[a-z][a-z0-9]*(-[a-z0-9]+)*$/`
+  - [x] 2.2: Auto-prepends `bmm-` if missing, sets `normalized: true`, handler prints `Agent name normalized to '<name>'`
+  - [x] 2.3: Checks against CUSTOM_AGENTS + BUILTIN_AGENTS + existing filesystem files
+- [x] Task 3: Interactive agent definition wizard (AC: #1)
+  - [x] 3.1: `generateAgentTemplate` produces template persona placeholders
+  - [x] 3.2: Template includes placeholder menu item
+  - [x] 3.3: MANDATORY_CRITICAL_ACTIONS 1-3 always included
+  - [x] 3.4: File is editable for additional critical_actions (placeholder comment)
+- [x] Task 4: Generate agent files (AC: #1, #3)
+  - [x] 4.1: Generates `lib/bmad-extension/agents/<agent-name>.customize.yaml`
+  - [x] 4.2: YAML block style, quoted action strings
+  - [x] 4.3: Header comment includes agent name and "Generated by ma-agents create-agent"
+  - [x] 4.4: module-help.csv not updated — CSV maps workflows to agents, not agents; no entry needed for new agents without workflows
+- [x] Task 5: Print next steps guidance (AC: #3)
+  - [x] 5.1: Prints `Agent '<agent-name>' created at lib/bmad-extension/agents/...`
+  - [x] 5.2: Prints 4-step next steps guidance including recompile instruction
+- [x] Task 6: Test the command
+  - [x] 6.1: `createBmadAgent` unit tests — file creation, persona, menu, critical_actions (4 tests)
+  - [x] 6.2: Duplicate returns `{ success: false, error, hint }` — label-free (2 tests)
+  - [x] 6.3: `validateAgentName` tests — auto-prefix, pattern, conflicts (7 tests)
+  - [x] 6.4: CLI integration tests — no name, existing agent, invalid, --yes, auto-prefix (5 tests)
+
+## Dev Notes
+
+### Architecture Compliance
+
+- **New agents are "custom" type:** All user-created agents get full customization (persona + menu + critical_actions), same as SRE/DevOps/Cyber/MIL-498. They are NOT "built-in" — built-in agents are the 7 standard BMM agents that ship with bmad-method. [Source: architecture.md#Decision-P2-4]
+- **Extension module deployment:** New agents live in `lib/bmad-extension/agents/` and are deployed to the BMAD installation via `bmad.js` during install. No changes to `bmad.js` needed — it copies the entire extension directory. [Source: architecture.md#Decision-P2-3]
+- **critical_actions 1-3 are immutable** and identical to all other agents. [Source: architecture.md#Decision-P2-4]
+- **BMAD naming convention:** Agent names use `bmm-` prefix + kebab-case role (e.g., `bmm-sre`, `bmm-devops`). [Source: architecture.md#Naming-Patterns]
+
+### Relationship to Story 3-4
+
+This story creates NEW agents. Story 3-4 customizes EXISTING agents. They share:
+- Same output directory (`lib/bmad-extension/agents/`)
+- Same `.customize.yaml` format
+- Same critical_actions 1-3 template
+- Same module (`lib/skill-authoring.js`)
+
+The key difference: `create-agent` always generates full customization (custom agent), while `customize-agent` respects the built-in vs custom distinction.
+
+### module-help.csv Registration
+
+The BMAD `module-help.csv` maps agent names to their capabilities for phase registration. New custom agents may need an entry here. Check the existing CSV format:
+- If it maps agent-name -> available workflows, add the new agent
+- If it only lists module-level registration, no change needed
+
+### Interactive Prompts and --yes Mode
+
+Like Story 3-4, agent creation is inherently interactive (persona requires human input). In `--yes` mode, either skip or generate a minimal placeholder that the user edits manually.
+
+### Critical Guardrails
+
+- **critical_actions 1-3 are NEVER modifiable** [Source: architecture.md#Decision-P2-4]
+- **New agents are always "custom" type** — full persona + menu + critical_actions
+- **YAML block style, quoted strings** [Source: architecture.md#Extension-Module-Authoring-Patterns]
+- **`bmm-` prefix required** for BMAD agent naming [Source: architecture.md#Naming-Patterns]
+- **Use `path.join()` for all paths** [Source: architecture.md#Enforcement-Guidelines]
+- **No new npm dependencies** [Source: architecture.md#Anti-Patterns]
+
+### Project Structure Notes
+
+- Files to modify: `bin/cli.js` (add command route), `lib/skill-authoring.js` (add function)
+- Files created by the tool: `lib/bmad-extension/agents/<agent-name>.customize.yaml`
+- Possibly modify: `lib/bmad-extension/module-help.csv` (agent registration)
+
+### References
+
+- [Source: _bmad-output/planning-artifacts/prd.md#FR42] — FR42: Develop new specialized agent personas
+- [Source: _bmad-output/planning-artifacts/architecture.md#Decision-P2-3] — Extension module structure
+- [Source: _bmad-output/planning-artifacts/architecture.md#Decision-P2-4] — critical_actions patterns, custom vs built-in
+- [Source: _bmad-output/planning-artifacts/architecture.md#Extension-Module-Authoring-Patterns] — YAML format and rules
+- [Source: _bmad-output/planning-artifacts/architecture.md#Naming-Patterns] — bmm- prefix convention
+- [Source: lib/bmad-extension/agents/] — Target directory for agent files
+- [Source: lib/bmad-extension/module-help.csv] — Phase registration file
+
+## Dev Agent Record
+
+### Agent Model Used
+
+claude-sonnet-4-6
+
+### Debug Log References
+
+None — `module-help.csv` decision: CSV maps workflows to agents, not agents themselves. New agents without pre-defined workflows need no CSV entry; confirmed by inspecting existing CSV format.
+
+### Completion Notes List
+
+- Added `validateAgentName`, `createBmadAgent`, `generateAgentTemplate`, `handleCreateAgent` to `lib/skill-authoring.js`
+- `validateAgentName` auto-prepends `bmm-` (returns `normalized: true`), validates pattern, checks ALL_KNOWN_AGENTS set
+- `createBmadAgent` generates template-filled YAML: persona + menu (with placeholders) + mandatory critical_actions 1-3
+- `handleCreateAgent` informs user of normalization; checks filesystem conflict in addition to known agent lists
+- module-help.csv: no update needed — CSV only registers workflows, not agent definitions
+- Added `handleCreateAgent` import and `create-agent` switch case to `bin/cli.js`
+- Added `create-agent` to help text
+- Created `test/create-agent.test.js` with 18 tests: 13 unit + 5 CLI integration, all passing
+- 102 total project tests passing (was 84)
+
+### File List
+
+- `lib/skill-authoring.js` (modified — added validateAgentName, createBmadAgent, generateAgentTemplate, handleCreateAgent)
+- `bin/cli.js` (modified — import, switch case, help text)
+- `test/create-agent.test.js` (new)
+- `package.json` (modified — added create-agent.test.js to test script)
+
+### Change Log
+
+- 2026-03-19: Implemented Story 3.5 — create-agent command, validateAgentName (auto-prefix + validation), createBmadAgent (template scaffold), 18 tests