convoke-agents 3.0.4 → 3.2.0

package/_bmad/bme/_team-factory/workflows/add-team/step-04-generate.md

@@ -0,0 +1,160 @@
+# Step 04: Generate — File Creation & Integration Wiring
+
+## Purpose
+Generate all team files through BMB delegation for content artifacts and factory JS utilities for integration wiring. This is the step where decisions become files.
+
+## Prerequisites
+- Step 03 (Review) completed — contributor approved all decisions
+- Spec file has progress.review = "complete"
+
+## Execution Sequence
+
+### 1. Load Spec & Plan Generation
+
+Read the spec file. Build the generation plan:
+
+**Files to generate (per agent):**
+1. Agent definition file: `_bmad/bme/_{team}/agents/{agent_id}.md`
+2. Workflow files: `_bmad/bme/_{team}/workflows/{workflow_name}/workflow.md` + step files
+3. Contract files (Sequential): `_bmad/bme/_{team}/contracts/{contract_id}.md`
+4. User guide: `_bmad/bme/_{team}/guides/{NAME}-USER-GUIDE.md`
+
+**Integration files (whole team):**
+5. Config: `_bmad/bme/_{team}/config.yaml`
+6. Module help CSV: `_bmad/bme/_{team}/module-help.csv`
+7. README: `_bmad/bme/_{team}/README.md`
+8. Compass routing (Sequential): `_bmad/bme/_{team}/compass-routing-reference.md`
+
+**Shared file modifications:**
+9. Registry block in `scripts/update/lib/agent-registry.js`
+
+Display the plan: "{N} files to create, 1 shared file to modify."
+
+### 2. Directory Structure
+
+Create the module directory tree:
+```
+_bmad/bme/_{team_name_kebab}/
+  agents/
+  workflows/
+  contracts/        (Sequential only)
+  guides/
+  config.yaml
+  module-help.csv
+  README.md
+```
+
+### 3. Agent Generation (Sequential, Per-Agent)
+
+For each agent in pipeline order:
+
+**3a. Agent Definition (BMB Delegation)**
+Delegate to BMB (Bond) to generate the agent `.md` file. Provide full context:
+- Agent ID, name, icon, role, title, capabilities
+- Team name and composition pattern
+- Config path: `_bmad/bme/_{team}/config.yaml`
+- Communication style guidance from spec
+
+The agent file must follow the standard BMAD agent template:
+- Frontmatter with name and description
+- Activation XML with config loading, menu, handlers, rules
+- Persona section (role, identity, communication_style, principles)
+- Menu items pointing to the agent's workflows
+
+**3b. Workflow Generation (BMB Delegation)**
+For each agent's workflows, delegate to BMB to generate:
+- `workflow.md` — entry point with step sequence
+- Step files — one per workflow step
+
+**3c. Per-Agent Validation**
+After generating each agent's files:
+```
+run: node -e "const av = require('{project-root}/_bmad/bme/_team-factory/lib/writers/activation-validator.js'); av.validateActivation('{agent_file_path}', '{config_path}').then(r => console.log(JSON.stringify(r)))"
+expect: result.valid === true → proceed to next agent
+        result.valid === false → display errors, fix before continuing
+```
+
+**3d. Update Progress**
+Update spec file: `progress.generate.{agent_id}: "complete"`
+
+### 4. Contract Generation (Sequential Only)
+
+For each contract in the spec:
+- Generate contract file at `_bmad/bme/_{team}/contracts/{contract_id}.md`
+- Include: frontmatter (contract ID, source, targets, type), artifact schema, key sections
+- Follow existing contract patterns (Vortex HC1-HC10, Gyre GC1-GC4)
+
+### 5. Integration Wiring (Factory-Owned)
+
+**5a. Config Creation**
+```
+run: node -e "const cc = require('{project-root}/_bmad/bme/_team-factory/lib/writers/config-creator.js'); cc.createConfig({spec_data}).then(r => console.log(JSON.stringify(r)))"
+expect: result.success === true
+```
+
+**5b. CSV Creation**
+```
+run: node -e "const csv = require('{project-root}/_bmad/bme/_team-factory/lib/writers/csv-creator.js'); csv.createCsv({spec_data}).then(r => console.log(JSON.stringify(r)))"
+expect: result.success === true
+```
+
+**5c. Registry Block (Full Write Safety Protocol)**
+```
+run: node -e "const rw = require('{project-root}/_bmad/bme/_team-factory/lib/writers/registry-writer.js'); rw.writeRegistryBlock({spec_data}, '{registry_path}').then(r => console.log(JSON.stringify(r)))"
+expect: result.success === true → proceed
+        result.dirty === true → warn contributor, ask for confirmation
+        result.success === false → display errors, attempt rollback
+```
+
+**IMPORTANT:** The registry write uses the Full Write Safety Protocol:
+1. **Stage** — Build module block in memory
+2. **Validate** — Syntax check, prefix uniqueness, additive-only
+3. **Check** — Dirty-tree detection (git diff on agent-registry.js)
+4. **Apply** — Backup → write → verify
+5. **Verify** — Re-read + `node require()` post-write validation
+
+Show contributor: "Here's what will be added to agent-registry.js: [preview block]. Approve?"
+
+### 6. Compass Routing (Sequential Only)
+
+Generate `compass-routing-reference.md` with:
+- Navigation table mapping workflows to agents
+- "What do I do next?" routing for each workflow completion
+- Cross-team routing suggestions if applicable
+
+### 7. README Generation
+
+Generate `README.md` with:
+- Team description and purpose
+- Agent roster with roles
+- Quick start instructions
+- Workflow overview
+
+### 8. Manifest Tracking
+
+Track all created and modified files:
+```
+run: node -e "const mt = require('{project-root}/_bmad/bme/_team-factory/lib/manifest-tracker.js'); mt.buildManifest({spec_data}).then(r => console.log(JSON.stringify(r)))"
+```
+
+### 9. Save Progress
+
+Update spec file: `progress.generate: "complete"` (all agents done)
+
+Display: "Generation complete. {N} files created, 1 file modified. Moving to validation."
+
+Proceed to: `{project-root}/_bmad/bme/_team-factory/workflows/add-team/step-05-validate.md`
+
+## Visibility Checklist — Step 4
+Colleague sees:
+  - [ ] Generation plan (file count and list)
+  - [ ] Per-agent progress ("Generating agent {name}...")
+  - [ ] Registry block preview + approval prompt
+Runs silently:
+  - [ ] BMB delegation calls
+  - [ ] Activation validation per agent
+  - [ ] Config/CSV creation
+  - [ ] Write Safety Protocol (registry)
+  - [ ] Manifest tracking
+Concept count: 2/3 (generation progress, registry approval)
+Approval prompt: "Here's what will be added to agent-registry.js — approve?"

package/_bmad/bme/_team-factory/workflows/add-team/step-05-validate.md

@@ -0,0 +1,146 @@
+# Step 05: Validate — End-to-End Verification & Completion
+
+## Purpose
+Run comprehensive validation on the generated team, produce a file manifest, collect metrics, and conclude the factory run.
+
+## Prerequisites
+- Step 04 (Generate) completed — all files created and wired
+- Spec file has progress.generate = "complete" (or all agent sub-entries complete)
+
+## Execution Sequence
+
+### 1. Load Spec & Manifest
+
+Read the spec file and the generation manifest (list of all created/modified files).
+
+### 2. End-to-End Validation
+
+Run the full validation suite:
+
+```
+run: node -e "const v = require('{project-root}/_bmad/bme/_team-factory/lib/validators/end-to-end-validator.js'); v.validateTeam({spec_data}, '{project-root}').then(r => console.log(JSON.stringify(r, null, 2)))"
+expect: result.valid === true → all checks passed
+        result.valid === false → display failing checks with details
+```
+
+The end-to-end validator checks:
+
+**Structural checks:**
+- Config.yaml exists and parses correctly
+- Every agent file declared in config exists
+- Every workflow has a workflow.md entry point
+- Contract files exist (Sequential only)
+- README exists
+
+**Wiring checks:**
+- Agent registry block exists with correct prefix
+- All agents appear in the registry AGENTS array
+- All workflows appear in the registry WORKFLOWS array
+- Derived lists (AGENT_FILES, AGENT_IDS, WORKFLOW_NAMES) are correct
+- Registry file passes `node require()` verification
+
+**Naming checks:**
+- Module directory matches `_{team_name_kebab}`
+- Agent file names match agent IDs
+- All names conform to naming conventions
+
+**Pattern-specific checks (Sequential only):**
+- At least one handoff contract exists
+- Contract source/target agents match agent list
+- Compass routing reference exists
+
+### 3. Regression Check
+
+Verify that existing teams still pass validation:
+```
+run: node -e "require('{project-root}/scripts/update/lib/validator.js')" logic
+```
+
+This confirms the factory's changes to shared files (agent-registry.js) didn't break existing teams.
+
+### 4. Display Results
+
+**If all checks pass:**
+```
+═══════════════════════════════════════════════════
+  ✅ TEAM FACTORY — Validation Complete
+═══════════════════════════════════════════════════
+
+  Team:     {team_name} (_{team_name_kebab})
+  Pattern:  {composition_pattern}
+  Agents:   {count}
+  Checks:   {passed}/{total} passed
+
+  FILES CREATED:
+  ├── _bmad/bme/_{team}/config.yaml
+  ├── _bmad/bme/_{team}/module-help.csv
+  ├── _bmad/bme/_{team}/README.md
+  ├── _bmad/bme/_{team}/agents/{agent_id}.md
+  ├── _bmad/bme/_{team}/workflows/...
+  ├── _bmad/bme/_{team}/contracts/...     [Sequential]
+  └── _bmad/bme/_{team}/guides/...
+
+  FILES MODIFIED:
+  └── scripts/update/lib/agent-registry.js
+
+  Spec file: _bmad-output/planning-artifacts/team-spec-{team}.yaml
+
+═══════════════════════════════════════════════════
+```
+
+**If checks fail:**
+Display each failing check with:
+- Check name (e.g., CONFIG-EXISTS, REGISTRY-BLOCK)
+- Step name (structural, wiring, naming, pattern)
+- Expected vs actual values (per TF-NFR11)
+- Suggested fix
+
+Ask: "Would you like to fix these issues and re-validate, or save current state and resume later?"
+
+### 5. Post-Completion Metrics
+
+If validation passed, collect two brief metrics:
+1. "What was the hardest step?" (orient/scope/connect/review/generate/validate)
+2. "Would you use the factory again?" (yes/no/maybe)
+
+Store in spec file metrics section. These feed self-instrumentation (concern #9).
+
+### 6. Save Final State
+
+Update spec file:
+- progress.validate = "complete"
+- metrics populated
+
+### 7. Next Steps
+
+Display guidance:
+> "Your team **{team_name}** is ready! Here's what to do next:
+>
+> 1. **Review generated files** — Check agent personas, workflow steps, and contract schemas
+> 2. **Fill in domain content** — The factory created structural skeletons; add your domain expertise
+> 3. **Run `convoke-doctor`** — Verify the team passes framework-level validation
+> 4. **Test with a real workflow** — Invoke one of your agents and run through a workflow
+> 5. **Iterate** — Use the factory's Add Agent (Phase 3) to extend your team later
+>
+> Spec file saved at: `_bmad-output/planning-artifacts/team-spec-{team}.yaml`
+> This file is your audit trail and can be used with Express Mode to recreate the team."
+
+### 8. Abort Path (If Requested)
+
+If the contributor requests abort at any point:
+- Display the file manifest: "The following files were created during this factory run:"
+- List each file with its path
+- Provide removal instructions: "To remove all generated files, delete the following paths:"
+- Note: "The spec file at {path} will be preserved for your records."
+
+## Visibility Checklist — Step 5
+Colleague sees:
+  - [ ] Validation results summary (pass/fail per check)
+  - [ ] Complete file manifest
+  - [ ] Next steps guidance
+Runs silently:
+  - [ ] End-to-end validation suite
+  - [ ] Regression check on existing teams
+  - [ ] Manifest generation
+Concept count: 2/3 (validation results, next steps)
+Approval prompt: N/A — this is the final step

package/_bmad/bme/_team-factory/workflows/step-00-route.md

@@ -0,0 +1,76 @@
+# Step 00: Intent Routing
+
+## Purpose
+Classify the contributor's intent and route to the correct factory workflow.
+This step is LLM-heavy — a colleague saying "I want to automate onboarding" requires reasoning about whether that's a team, an agent addition, or a skill addition.
+
+## Execution
+
+### Mode Detection
+
+Check if this was invoked with data context:
+- **data="resume"** → Load existing spec file, run `spec-differ.js` to find resume point, jump to that step
+- **data="express"** → Ask for spec file path, load it, validate with `spec-parser.js`, jump to step-03-review
+- **No data** → Proceed with intent classification below
+
+### Intent Classification
+
+Ask the contributor what they want to do. Listen for natural language descriptions and classify:
+
+| Intent Signal | Route To |
+|---------------|----------|
+| "Create a new team", "build a team", "add a team module" | **add-team** workflow → step-01-scope.md |
+| "Add an agent to [existing team]", "extend [team] with a new agent" | **add-agent** workflow (Phase 3 — not yet available) |
+| "Add a skill/workflow to [agent]", "extend [agent]" | **add-skill** workflow (Phase 3 — not yet available) |
+| Unclear / doesn't match | Ask clarifying question: "Are you looking to create an entirely new team, add an agent to an existing team, or add a workflow to an existing agent?" |
+
+### For "Create Team" (Primary Flow)
+
+1. Confirm the contributor wants to create a new team
+2. Brief them on what the factory will do:
+   > "We'll walk through 5 steps together:
+   > 1. **Scope** — Define your team's agents, their roles, and how they work together
+   > 2. **Connect** — Design integration wiring (contracts, config, routing)
+   > 3. **Review** — Summary of all decisions for your approval
+   > 4. **Generate** — Create all files via BMB delegation + integration wiring
+   > 5. **Validate** — End-to-end validation confirming everything works
+   >
+   > At any point you can save progress and resume later."
+
+3. Proceed to: `{project-root}/_bmad/bme/_team-factory/workflows/add-team/step-01-scope.md`
+
+### For Phase 3 Workflows (Not Yet Available)
+
+Display:
+> "Add Agent and Add Skill workflows are planned for Phase 3 of the Team Factory. For now, you can:
+> 1. Use the Architecture Reference ([AR] from the menu) to understand what's needed
+> 2. Use BMB (Bond) to generate individual agent or workflow files
+> 3. Manually wire integration following the reference checklist"
+
+### Resume Mode
+
+1. Ask for the path to an existing `team-spec-*.yaml` file
+2. Run: `node {project-root}/_bmad/bme/_team-factory/lib/spec-differ.js` logic:
+   - Parse the spec file
+   - Find the first non-complete step in the progress section
+   - Display: "Found spec for team **{team_name}**. Progress: {completed steps}. Resuming from **{resume_step}**."
+3. Jump to the appropriate step file
+
+### Express Mode
+
+1. Ask for the path to a completed `team-spec-*.yaml` file
+2. Run: `node {project-root}/_bmad/bme/_team-factory/lib/spec-parser.js` logic:
+   - Parse and validate the spec file against the appropriate schema
+   - If validation fails: display errors, ask contributor to fix the spec file
+   - If validation passes: display decision summary and jump to step-03-review.md
+
+## Visibility Checklist — Step 0
+Colleague sees:
+  - [ ] Intent classification question or mode confirmation
+  - [ ] Brief overview of factory steps (for Create Team)
+  - [ ] Resume point summary (for Resume mode)
+Runs silently:
+  - [ ] Spec file parsing and validation (Resume/Express)
+  - [ ] Resume point detection (Resume)
+Concept count: 2/3
+Approval prompt: "Ready to start creating your team?"

package/_bmad/bme/_vortex/config.yaml

@@ -1,7 +1,7 @@
 submodule_name: _vortex
 description: Vortex Pattern - Contextualize, Empathize, Externalize, and Systematize streams
 module: bme
-output_folder: '{project-root}/_bmad-output/vortex-artifacts'
+output_folder: "{project-root}/_bmad-output/vortex-artifacts"
 agents:
   - contextualization-expert
   - discovery-empathy-expert
@@ -33,13 +33,13 @@ workflows:
   - learning-card
   - pivot-patch-persevere
   - vortex-navigation
-version: 3.0.4
-user_name: '{user}'
+version: 3.2.0
+user_name: "{user}"
 communication_language: en
 party_mode_enabled: true
 core_module: bme
 migration_history:
-  - timestamp: '2026-02-27T13:26:05.803Z'
+  - timestamp: 2026-02-27T13:26:05.803Z
     from_version: 1.5.2
     to_version: 1.6.2
     migrations_applied: