# 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
