brachnha-insight/_bmad/bmb/workflows/module/steps-v/step-04-agent-specs.md

name, description, nextStepFile, agentSpecTemplate, agentArchitectureFile, agentValidationWorkflow, validationReportOutput, targetPath

name	description	nextStepFile	agentSpecTemplate	agentArchitectureFile	agentValidationWorkflow	validationReportOutput	targetPath
step-04-agent-specs	Validate agent specifications and built agents	./step-05-workflow-specs.md	../../templates/agent-spec-template.md	../../data/agent-architecture.md	{project-root}/_bmad/bmb/workflows/agent/steps-v/step-01-validate.md	{validation_report_output}	{validation_target_path}

Step 4: Agent Specs Validation

STEP GOAL:

Validate agent specifications and/or built agents, distinguishing between placeholder specs and fully implemented agents.

MANDATORY EXECUTION RULES:

Universal Rules:

• 📖 CRITICAL: Read the complete step file before taking any action
• ✅ Speak in {communication_language}

Role Reinforcement:

• ✅ You are the Quality Assurance — dual-mode checking
• ✅ Specs are expected, built agents are great
• ✅ Track status of each agent

---

MANDATORY SEQUENCE

1. Load Agent Files

Find all agent files in {targetPath}/agents/:

• .spec.md files (placeholder specs)
• .agent.yaml files (built agents)

2. Categorize Agents

For each agent found, determine status:

Built Agents (.agent.yaml):

• Full implementation with complete persona, menu YAML
• Can be validated in-depth via agent validation workflow

Spec Agents (.spec.md):

• High-level placeholder/blueprint
• Awaiting creation via agent-builder workflow

Track counts:

• Total agents: {count}
• Built agents: {count}
• Spec agents: {count}

3. Validate Spec Agents (.spec.md)

For each spec agent, check:

Required Sections:

• Agent metadata (id, name, title, icon, module)
• Role defined
• Identity or communication style
• Menu triggers documented
• hasSidecar decision documented

Menu Triggers:

• At least one trigger per agent
• Trigger → workflow mapping clear
• No duplicate triggers (warn if found)

hasSidecar Documentation:

• Decision documented (true or false)
• Rationale if true (why memory needed)

Placeholder Note: These are specs awaiting agent-builder.

4. Validate Built Agents (.agent.yaml)

For each built agent, check:

Frontmatter Completeness:

• agent.metadata exists
• agent.persona exists
• agent.menu exists

YAML Structure:

• Valid YAML syntax
• Required fields present

Status: These are complete implementations and can be validated in detail via sub-process.

5. Record Results

Append to {validationReportOutput}:

## Agent Specs Validation

**Status:** {PASS/FAIL/WARNINGS}

**Agent Summary:**
- Total Agents: {count}
- Built Agents: {count} {list}
- Spec Agents: {count} {list}

**Built Agents:**
{for each built agent}
- **{name}**: {status} - Ready for detailed validation via agent workflow

**Spec Agents:**
{for each spec agent}
- **{name}**: {status} - Placeholder awaiting agent-builder

**Issues Found:**
{list any issues}

**Recommendations:**
{if specs exist}
- Use `bmad:bmb:agents:agent-builder` to create {spec agent names}
- After building agents, re-run validation to verify compliance
{endif}

6. Note Sub-Process Opportunity

IF built agents exist:

"The following built agents can be validated in detail:"

{list built agents}

"After this validation completes, I can spawn sub-processes to run the agent validation workflow on each built agent for deeper compliance checking."

7. Auto-Proceed

"✓ Agent specs check complete."

Proceeding to next validation...

Load {nextStepFile}

---

Success Metrics

✅ All agent files checked ✅ Status tracked (spec vs built) ✅ hasSidecar decisions validated ✅ Recommendations for specs documented ✅ Sub-process opportunity noted