Mathias STRASSER
aedde6707e
Les enseignants ont besoin de moyennes à jour immédiatement après la publication ou modification des notes, sans attendre un batch nocturne. Le système recalcule via Domain Events synchrones : statistiques d'évaluation (min/max/moyenne/médiane), moyennes matières pondérées (normalisation /20), et moyenne générale par élève. Les résultats sont stockés dans des tables dénormalisées avec cache Redis (TTL 5 min). Trois endpoints API exposent les données avec contrôle d'accès par rôle. Une commande console permet le backfill des données historiques au déploiement.
156 lines
8.6 KiB
Markdown
156 lines
8.6 KiB
Markdown
---
|
|
name: build-process
|
|
description: 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 conversational discovery. Your north star: **outcome-driven design**. Every capability prompt should describe what to achieve, not prescribe how. The agent's persona and identity context inform HOW — capability prompts just need the WHAT. Only add procedural detail where the LLM would genuinely fail without it.
|
|
|
|
## Phase 1: Discover Intent
|
|
|
|
Understand their vision before diving into specifics. Ask what they want to build and encourage detail.
|
|
|
|
### When given an existing agent
|
|
|
|
**Critical:** Treat the existing agent as a **description of intent**, not a specification to follow. Extract _who_ this agent is and _what_ it achieves. Do not inherit its verbosity, structure, or mechanical procedures — the old agent is reference material, not a template.
|
|
|
|
If the SKILL.md routing already asked the 3-way question (Analyze/Edit/Rebuild), proceed with that intent. Otherwise ask now:
|
|
|
|
- **Edit** — changing specific behavior while keeping the current approach
|
|
- **Rebuild** — rethinking from core outcomes and persona, full discovery using the old agent as context
|
|
|
|
For **Edit**: identify what to change, preserve what works, apply outcome-driven principles to the changed portions.
|
|
|
|
For **Rebuild**: read the old agent to understand its goals and personality, then proceed through full discovery as if building new.
|
|
|
|
### Discovery questions (don't skip these, even with existing input)
|
|
|
|
The best agents come from understanding the human's vision directly. Walk through these conversationally — adapt based on what the user has already shared:
|
|
|
|
- **Who IS this agent?** What personality should come through? What's their voice?
|
|
- **How should they make the user feel?** What's the interaction model — conversational companion, domain expert, silent background worker, creative collaborator?
|
|
- **What's the core outcome?** What does this agent help the user accomplish? What does success look like?
|
|
- **What capabilities serve that core outcome?** Not "what features sound cool" — what does the user actually need?
|
|
- **What's the one thing this agent must get right?** The non-negotiable.
|
|
- **If memory/sidecar:** What's worth remembering across sessions? What should the agent track over time?
|
|
|
|
The goal is to conversationally gather enough to cover Phase 2 and 3 naturally. Since users often brain-dump rich detail, adapt subsequent phases to what you already know.
|
|
|
|
## 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.
|
|
|
|
**Script Opportunity Discovery** (active probing — do not skip):
|
|
|
|
Identify deterministic operations that should be scripts. Load `./references/script-opportunities-reference.md` for guidance. Confirm the script-vs-prompt plan with the user before proceeding. If any scripts require external dependencies (anything beyond Python's standard library), explicitly list each dependency and get user approval — dependencies add install-time cost and require `uv` to be available.
|
|
|
|
## Phase 3: Gather Requirements
|
|
|
|
Gather through conversation: identity, capabilities, activation modes, memory needs, access boundaries. Refer to `./references/standard-fields.md` for conventions.
|
|
|
|
Key structural context:
|
|
|
|
- **Naming:** Standalone: `bmad-agent-{name}`. Module: `bmad-{modulecode}-agent-{name}`
|
|
- **Activation modes:** Interactive only, or Interactive + Headless (schedule/cron for background tasks)
|
|
- **Memory architecture:** Sidecar at `{project-root}/_bmad/memory/{skillName}-sidecar/`
|
|
- **Access boundaries:** Read/write/deny zones stored in memory
|
|
|
|
**If headless mode enabled, also gather:**
|
|
|
|
- Default wake behavior (`--headless` | `-H` with no specific task)
|
|
- Named tasks (`--headless:{task-name}` or `-H:{task-name}`)
|
|
|
|
**Path conventions (CRITICAL):**
|
|
|
|
- Memory: `{project-root}/_bmad/memory/{skillName}-sidecar/`
|
|
- Project artifacts: `{project-root}/_bmad/...`
|
|
- Skill-internal: `./references/`, `./scripts/`
|
|
- Config variables used directly — they already contain full paths (no `{project-root}` prefix)
|
|
|
|
## Phase 4: Draft & Refine
|
|
|
|
Think one level deeper. Present a draft outline. Point out vague areas. Iterate until ready.
|
|
|
|
**Pruning check (apply before building):**
|
|
|
|
For every planned instruction — especially in capability prompts — ask: **would the LLM do this correctly given just the agent's persona and the desired outcome?** If yes, cut it.
|
|
|
|
The agent's identity, communication style, and principles establish HOW the agent behaves. Capability prompts should describe WHAT to achieve. If you find yourself writing mechanical procedures in a capability prompt, the persona context should handle it instead.
|
|
|
|
Watch especially for:
|
|
|
|
- Step-by-step procedures in capabilities that the LLM would figure out from the outcome description
|
|
- Capability prompts that repeat identity/style guidance already in SKILL.md
|
|
- Multiple capability files that could be one (or zero — does this need a separate capability at all?)
|
|
- Templates or reference files that explain things the LLM already knows
|
|
|
|
## Phase 5: Build
|
|
|
|
**Load these before building:**
|
|
|
|
- `./references/standard-fields.md` — field definitions, description format, path rules
|
|
- `./references/skill-best-practices.md` — outcome-driven authoring, patterns, anti-patterns
|
|
- `./references/quality-dimensions.md` — build quality checklist
|
|
|
|
Build the agent using templates from `./assets/` and rules from `./references/template-substitution-rules.md`. Output to `{bmad_builder_output_folder}`.
|
|
|
|
**Capability prompts are outcome-driven:** Each `./references/{capability}.md` file should describe what the capability achieves and what "good" looks like — not prescribe mechanical steps. The agent's persona context (identity, communication style, principles in SKILL.md) informs how each capability is executed. Don't repeat that context in every capability prompt.
|
|
|
|
**Agent structure** (only create subfolders that are needed):
|
|
|
|
```
|
|
{skill-name}/
|
|
├── SKILL.md # Persona, activation, capability routing
|
|
├── references/ # Progressive disclosure content
|
|
│ ├── {capability}.md # Each internal capability prompt
|
|
│ ├── memory-system.md # Memory discipline (if sidecar)
|
|
│ ├── init.md # First-run onboarding (if sidecar)
|
|
│ ├── autonomous-wake.md # Headless activation (if headless)
|
|
│ └── save-memory.md # Explicit memory save (if sidecar)
|
|
├── assets/ # Templates, starter files
|
|
└── scripts/ # Deterministic code with tests
|
|
```
|
|
|
|
| Location | Contains | LLM relationship |
|
|
| ------------------- | ---------------------------------- | ------------------------------------ |
|
|
| **SKILL.md** | Persona, activation, routing | LLM identity and router |
|
|
| **`./references/`** | Capability prompts, reference data | Loaded on demand |
|
|
| **`./assets/`** | Templates, starter files | Copied/transformed into output |
|
|
| **`./scripts/`** | Python, shell scripts with tests | Invoked for deterministic operations |
|
|
|
|
**Activation guidance for built agents:**
|
|
|
|
Activation is a single flow regardless of mode. It should:
|
|
|
|
- Load config and resolve values (with defaults)
|
|
- Load sidecar `index.md` if the agent has memory
|
|
- If headless, route to `./references/autonomous-wake.md`
|
|
- If interactive, greet the user and continue from memory context or offer capabilities
|
|
|
|
**If the built agent includes scripts**, also load `./references/script-standards.md` — ensures PEP 723 metadata, correct shebangs, and `uv run` invocation from the start.
|
|
|
|
**Lint gate** — after building, validate and auto-fix:
|
|
|
|
If subagents available, delegate lint-fix to a subagent. Otherwise run inline.
|
|
|
|
1. Run both lint scripts in parallel:
|
|
```bash
|
|
python3 ./scripts/scan-path-standards.py {skill-path}
|
|
python3 ./scripts/scan-scripts.py {skill-path}
|
|
```
|
|
2. Fix high/critical findings and re-run (up to 3 attempts per script)
|
|
3. Run unit tests if scripts exist in the built skill
|
|
|
|
## Phase 6: Summary
|
|
|
|
Present what was built: location, structure, first-run behavior, capabilities.
|
|
|
|
Run unit tests if scripts exist. Remind user to commit before quality analysis.
|
|
|
|
**Offer quality analysis:** Ask if they'd like a Quality Analysis to identify opportunities. If yes, load `quality-analysis.md` with the agent path.
|