calctext/.agents/skills/bmad-agent-builder/build-process.md

name, description

name	description
build-process	Six-phase conversational discovery process for building BMad agents. Covers intent discovery, capabilities strategy, requirements gathering, drafting, building, and summary.

Language: Use {communication_language} for all output.

Build Process

Build AI agents through six phases of conversational discovery. Act as an architect guide — probe deeper than what users articulate, suggest what they haven't considered, and build something that exceeds what they imagined.

Phase 1: Discover Intent

Understand their vision before diving into specifics. Ask what they want to build and encourage detail.

If editing/converting an existing agent: read it, analyze what exists vs what's missing, understand what needs changing and specifically ensure it conforms to our standard with building new agents upon completion.

Phase 2: Capabilities Strategy

Early check: internal capabilities only, external skills, both, or unclear?

If external skills involved: Suggest bmad-module-builder to bundle agents + skills into a cohesive module. Modules are the heart of the BMad ecosystem — shareable packages for any domain.

Script Opportunity Discovery (active probing — do not skip): Walk through each planned capability with the user and apply these filters:

1. "Does this operation have clear pass/fail criteria?" → Script candidate
2. "Could this run without LLM judgment — no interpretation, no creativity, no ambiguity?" → Strong script candidate
3. "Does it validate, transform, count, parse, format-convert, compare against a schema, or check structure?" → Almost certainly a script

Common script-worthy operations:

• Schema/format validation (JSON, YAML, frontmatter, file structure)
• Data extraction and transformation (parsing, restructuring, field mapping)
• Counting, aggregation, and metric collection (token counts, file counts, summary stats)
• File/directory structure checks (existence, naming conventions, required files)
• Pattern matching against known standards (path conventions, naming rules)
• Comparison operations (diff, version compare, before/after, cross-reference checking)
• Dependency graphing (parsing imports, references, manifest entries)
• Memory structure validation (required sections, path correctness)
• Access boundary extraction and verification
• Pre-processing for LLM capabilities (extract compact metrics from large files so the LLM works from structured data, not raw content)
• Post-processing validation (verify LLM output conforms to expected schema/structure)

Present your script plan: Before moving to Phase 3, explicitly tell the user which operations you plan to implement as scripts vs. prompts, with one-line reasoning for each. Ask if they agree or want to adjust.

If scripts are planned, the scripts/ folder will be created. Scripts are invoked from prompts when needed, not run automatically.

Phase 3: Gather Requirements

Work through these conversationally:

• Name: Functional (kebab-case), display name, title, icon
• Overview: Draft a 2-3 sentence overview following the 3-part formula:
  • What — What this agent does
  • How — Role, approach, or key capabilities
  • Why/Outcome — Value delivered or quality standard
  • Example: "This skill provides a {role} who helps users {outcome}. Act as {name} — {key quality}."
• Identity: Who is this agent? How do they communicate? What guides their decisions?
• Module context: Standalone (bmad-agent-{name}) or part of a module (bmad-{modulecode}-agent-{name})
• Activation modes:
  • Interactive only — User invokes the agent directly
  • Interactive + Autonomous — Also runs on schedule/cron for background tasks
• Memory & Persistence:
  • Sidecar needed? — What persists across sessions?
  • Critical data (must persist immediately): What data is essential to capture the moment it's created?
  • Checkpoint data (save periodically): What can be batched and saved occasionally?
  • Save triggers: After which interactions should memory be updated?
• Capabilities:
  • Internal prompts: Capabilities the agent knows itself (each will get its own prompt file)
  • External skills: Skills the agent invokes (ask for exact registered skill names — e.g., bmad-init, skill-creator)
    • Note: Skills may exist now or be created later
• First-run: What should it ask on first activation? (standalone only; module-based gets config from module's config.yaml)

If autonomous mode is enabled, ask additional questions:

• Autonomous tasks: What should the agent do when waking on a schedule?

  • Examples: Review/organize memory, process queue, maintenance tasks, implement tickets

• Default wake behavior: What happens with --headless | -H (no specific task)?

• Named tasks: What specific tasks can be invoked with --headless:{task-name} or -H:{task-name}?

• Folder Dominion / Access Boundaries:

  • What folders can this agent read from? (e.g., journals/, financials/, specific file patterns)
  • What folders can this agent write to? (e.g., output folders, log locations)
  • Are there any explicit deny zones? (folders the agent must never touch)
  • Store these boundaries in memory as the standard access-boundaries section (see memory-system template)

Key distinction: Folder dominion (where things live) ≠ agent memory (what persists across sessions)

• Path Conventions (CRITICAL for reliable agent behavior):
  • Memory location: {project-root}/_bmad/_memory/{skillName}-sidecar/
  • Project artifacts: {project-root}/_bmad/... when referencing project-level files
  • Skill-internal files: Use relative paths (references/, scripts/)
  • Config variables: Use directly — they already contain full paths (NO {project-root} prefix)
    • Correct: {output_folder}/file.md
    • Wrong: {project-root}/{output_folder}/file.md (double-prefix breaks resolution)
  • No absolute paths (/Users/...) or relative prefixes (./, ../)

Phase 4: Draft & Refine

Once you have a cohesive idea, think one level deeper. Once you have done this, present a draft outline. Point out vague areas. Ask what else is needed. Iterate until they say they're ready.

Phase 5: Build

Always load these before building:

• Load references/standard-fields.md — field definitions, description format, path rules
• Load references/skill-best-practices.md — authoring patterns (freedom levels, templates, anti-patterns)
• Load references/quality-dimensions.md — quick mental checklist for build quality

Load based on context:

• If module-based: Load references/metadata-reference.md — manifest.json field definitions, module metadata structure, config loading requirements
• Always load references/script-opportunities-reference.md — script opportunity spotting guide, catalog, and output standards. Use this to identify additional script opportunities not caught in Phase 2, even if no scripts were initially planned.

When confirmed:

1. Load template substitution rules from references/template-substitution-rules.md and apply

2. Create skill structure using templates from assets/ folder:

   • SKILL-template.md — skill wrapper with full persona content embedded
   • init-template.md — first-run setup (if sidecar)
   • memory-system.md — memory (if sidecar, saved at root level)
   • autonomous-wake.md — autonomous activation behavior (if activation_modes includes "autonomous")
   • save-memory.md — explicit memory save capability (if sidecar enabled)

3. Generate bmad-manifest.json — Use scripts/manifest.py (validation is automatic on every write). IMPORTANT: The generated manifest must NOT include a $schema field — the schema is used for validation tooling only and is not part of the delivered skill.

   # Create manifest with agent identity
   python3 scripts/manifest.py create {skill-path} \
     --persona "Succinct distillation of who this agent is" \
     --module-code {code}  # if part of a module \
     --has-memory           # if sidecar needed
   
   # Add each capability
   # NOTE: capability description must be VERY short — what it produces, not how it works
   python3 scripts/manifest.py add-capability {skill-path} \
     --name {name} --menu-code {MC} --description "Short: what it produces." \
     --supports-autonomous \
     --prompt {name}.md              # internal capability
     # OR --skill-name {skill}       # external skill
     # omit both if SKILL.md handles it directly
   
   # Module capabilities need sequencing metadata (confirm with user):
   # - phase-name: which module phase (e.g., "1-analysis", "2-design", "anytime")
   # - after: array of skill names that should run before this (inputs/dependencies)
   # - before: array of skill names this should run before (downstream consumers)
   # - is-required: if true, skills in 'before' are blocked until this completes
   # - description: VERY short — what it produces, not how it works
   python3 scripts/manifest.py add-capability {skill-path} \
     --name {name} --menu-code {MC} --description "Short: what it produces." \
     --phase-name anytime \
     --after skill-a skill-b \
     --before skill-c \
     --is-required
   

4. Folder structure:

{skill-name}/
├── SKILL.md               # Contains full persona content (agent.md embedded)
├── bmad-manifest.json     # Capabilities, persona, memory, module integration
├── init.md                # First-run setup (if sidecar)
├── autonomous-wake.md     # Autonomous activation (if autonomous mode)
├── save-memory.md         # Explicit memory save (if sidecar)
├── {name}.md              # Each internal capability prompt
├── references/            # Reference data, schemas, guides (read for context)
│   └── memory-system.md   # (if sidecar needed)
├── assets/                # Templates, starter files (copied/transformed into output)
└── scripts/               # Deterministic code — validation, transformation, testing
    └── run-tests.sh       # uvx-powered test runner (if python tests exist)

What goes where:

Location	Contains	LLM relationship
Root .md files	Prompt/instruction files, subagent definitions	LLM loads and executes these as instructions — they are extensions of SKILL.md
references/	Reference data, schemas, tables, examples, guides	LLM reads for context — informational, not executable
assets/	Templates, starter files, boilerplate	LLM copies/transforms these into output — not for reasoning
scripts/	Python, shell scripts with tests	LLM invokes these — deterministic operations that don't need judgment

Only create subfolders that are needed — most skills won't need all four.

5. Output to bmad_builder_output_folder from config, or {project-root}/bmad-builder-creations/

6. Lint gate — run deterministic validation scripts:

   python3 scripts/scan-path-standards.py {skill-path}
   python3 scripts/scan-scripts.py {skill-path}
   

   • If any script returns critical issues: fix them before proceeding
   • If only warnings/medium: note them but proceed

Phase 6: Summary

Present what was built: location, structure, first-run behavior, capabilities. Ask if adjustments needed.

After the build completes, offer quality optimization:

Ask: "Build is done. Would you like to run a Quality Scan to optimize the agent further?"

If yes, load quality-optimizer.md with {scan_mode}=full and the agent path.

Remind them: BMad module system compliant. Use bmad-init skill to integrate into a project.