ma-agents 3.6.2 → 3.8.0

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

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

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

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

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