convoke-agents 3.1.0 → 3.2.1

package/_bmad/bme/_team-factory/schemas/schema-sequential.json

@@ -0,0 +1,242 @@
+{
+  "$schema": "http://json-schema.org/draft-07/schema#",
+  "title": "Team Spec — Sequential Pattern",
+  "description": "Schema for Sequential composition pattern team specs. Agents form a pipeline with handoff contracts.",
+  "type": "object",
+  "required": [
+    "schema_version",
+    "team_name",
+    "team_name_kebab",
+    "composition_pattern",
+    "agents",
+    "contracts",
+    "integration"
+  ],
+  "additionalProperties": true,
+  "properties": {
+    "schema_version": {
+      "type": "string",
+      "pattern": "^\\d+\\.\\d+$",
+      "description": "Schema version (e.g., '1.0')"
+    },
+    "team_name": {
+      "type": "string",
+      "minLength": 1,
+      "description": "Human-readable team name"
+    },
+    "team_name_kebab": {
+      "type": "string",
+      "pattern": "^[a-z][a-z0-9]*(-[a-z0-9]+)*$",
+      "description": "Kebab-case team name for directory naming"
+    },
+    "description": {
+      "type": "string",
+      "description": "What the team does"
+    },
+    "composition_pattern": {
+      "type": "string",
+      "enum": ["Sequential"],
+      "description": "Must be 'Sequential' for this schema"
+    },
+    "created": {
+      "type": "string",
+      "description": "ISO date string"
+    },
+    "factory_version": {
+      "type": "string",
+      "description": "Factory version that created this spec"
+    },
+    "agents": {
+      "type": "array",
+      "minItems": 1,
+      "items": {
+        "type": "object",
+        "required": ["id", "role", "pipeline_position"],
+        "properties": {
+          "id": {
+            "type": "string",
+            "pattern": "^[a-z]+(-[a-z]+)*$",
+            "description": "Agent ID in kebab-case"
+          },
+          "name": {
+            "type": "string",
+            "description": "Display name (first name persona)"
+          },
+          "icon": {
+            "type": "string",
+            "description": "Single emoji"
+          },
+          "role": {
+            "type": "string",
+            "minLength": 1,
+            "description": "What this agent does"
+          },
+          "title": {
+            "type": "string",
+            "description": "Formal title"
+          },
+          "capabilities": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "pipeline_position": {
+            "type": "integer",
+            "minimum": 1,
+            "description": "Position in the pipeline (1-based)"
+          },
+          "overlap_acknowledgments": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "persona": {
+            "type": "object",
+            "properties": {
+              "role": { "type": "string" },
+              "identity": { "type": "string" },
+              "communication_style": { "type": "string" },
+              "expertise": { "type": "string" }
+            }
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "contracts": {
+      "type": "array",
+      "minItems": 1,
+      "description": "Handoff contracts between pipeline agents",
+      "items": {
+        "type": "object",
+        "required": ["id", "source_agent", "target_agents"],
+        "properties": {
+          "id": {
+            "type": "string",
+            "description": "Contract ID (e.g., HC1, GC1)"
+          },
+          "source_agent": {
+            "type": "string",
+            "description": "Agent ID that produces the artifact"
+          },
+          "target_agents": {
+            "type": "array",
+            "minItems": 1,
+            "items": { "type": "string" },
+            "description": "Agent IDs that consume the artifact"
+          },
+          "artifact_title": {
+            "type": "string",
+            "description": "Human-readable artifact name"
+          },
+          "artifact_description": {
+            "type": "string",
+            "description": "What the artifact contains"
+          },
+          "key_sections": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Main sections of the artifact"
+          },
+          "file_name": {
+            "type": "string",
+            "description": "Output file name for the artifact"
+          },
+          "input_artifacts": {
+            "type": "array",
+            "items": { "type": "string" },
+            "description": "Contract IDs this artifact depends on"
+          },
+          "optional": {
+            "type": "boolean",
+            "default": false,
+            "description": "Whether this contract is optional"
+          }
+        },
+        "additionalProperties": false
+      }
+    },
+    "feedback_contracts": {
+      "type": "array",
+      "description": "Optional feedback routing contracts (downstream → upstream)",
+      "items": {
+        "type": "object",
+        "required": ["id", "source_agent", "target_agents"],
+        "properties": {
+          "id": { "type": "string" },
+          "source_agent": { "type": "string" },
+          "target_agents": {
+            "type": "array",
+            "minItems": 1,
+            "items": { "type": "string" }
+          },
+          "artifact_title": { "type": "string" },
+          "artifact_description": { "type": "string" },
+          "key_sections": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "file_name": { "type": "string" },
+          "input_artifacts": {
+            "type": "array",
+            "items": { "type": "string" }
+          },
+          "optional": { "type": "boolean", "default": true }
+        },
+        "additionalProperties": false
+      }
+    },
+    "integration": {
+      "type": "object",
+      "required": ["output_directory", "contract_prefix"],
+      "properties": {
+        "output_directory": {
+          "type": "string",
+          "minLength": 1,
+          "description": "Where output artifacts are saved"
+        },
+        "compass_routing": {
+          "type": "string",
+          "enum": ["required", "shared-reference"],
+          "description": "Compass routing mode (required for Sequential)"
+        },
+        "contract_prefix": {
+          "type": "string",
+          "minLength": 1,
+          "pattern": "^[A-Z]+$",
+          "description": "Prefix for contract IDs (e.g., HC, GC, FG)"
+        }
+      },
+      "additionalProperties": false
+    },
+    "progress": {
+      "type": "object",
+      "properties": {
+        "orient": { "type": "string" },
+        "scope": { "type": "string" },
+        "connect": { "type": "string" },
+        "review": { "type": "string" },
+        "generate": {},
+        "validate": { "type": "string" }
+      }
+    },
+    "decisions": {
+      "type": "array",
+      "items": {
+        "type": "object",
+        "properties": {
+          "step": { "type": "string" },
+          "decision": { "type": "string" },
+          "default_accepted": { "type": "boolean" },
+          "rationale": { "type": "string" }
+        }
+      }
+    },
+    "metrics": {
+      "type": "object",
+      "properties": {
+        "discovery_path": {},
+        "hardest_step": {},
+        "would_use_again": {}
+      }
+    }
+  }
+}

package/_bmad/bme/_team-factory/templates/team-spec-template.yaml

@@ -0,0 +1,86 @@
+# Team Spec Template — Express Mode Input
+# Fill in this template and pass to the factory for rapid team creation.
+# Fields marked REQUIRED must be provided. Optional fields can be removed.
+#
+# Usage: Save as team-spec-{your-team-name}.yaml in _bmad-output/planning-artifacts/
+# Then invoke the factory in Express Mode with this file as input.
+
+schema_version: "1.0"
+
+# REQUIRED: Human-readable team name
+team_name: ""
+
+# REQUIRED: Kebab-case team name (used for directory naming)
+# Must match: /^[a-z][a-z0-9]*(-[a-z0-9]+)*$/
+team_name_kebab: ""
+
+# Optional: What does this team do?
+description: ""
+
+# REQUIRED: "Independent" or "Sequential"
+# Independent: Agents operate standalone, no contracts between them
+# Sequential: Agents form a pipeline with handoff contracts
+composition_pattern: ""
+
+# Auto-populated by factory
+created: ""
+factory_version: "1.0.0"
+
+# REQUIRED: At least one agent
+# Agent IDs must match: /^[a-z]+(-[a-z]+)*$/
+agents:
+  - id: ""
+    name: ""          # Display name (first name persona)
+    icon: ""          # Single emoji
+    role: ""          # REQUIRED: What this agent does
+    title: ""         # Formal title
+    capabilities:
+      - ""
+    # Sequential only — remove for Independent
+    # pipeline_position: 1
+    overlap_acknowledgments: []
+
+# Sequential only — remove entire section for Independent
+# At least one contract required for Sequential teams
+# contracts:
+#   - id: "HC1"
+#     source_agent: ""
+#     target_agents:
+#       - ""
+#     artifact_title: ""
+#     artifact_description: ""
+#     key_sections:
+#       - ""
+#     file_name: ""
+#     input_artifacts: []
+#     optional: false
+
+# Sequential only — optional feedback routing contracts
+# feedback_contracts: []
+
+# REQUIRED: Integration settings
+integration:
+  output_directory: "_bmad-output/{team-name}-artifacts"
+  # "optional" or "per-agent" for Independent
+  # "required" or "shared-reference" for Sequential
+  compass_routing: ""
+  # Sequential only — prefix for contract IDs (e.g., "HC", "GC")
+  # contract_prefix: ""
+
+# Auto-managed by factory — do not edit manually
+progress:
+  orient: "pending"
+  scope: "pending"
+  connect: "pending"
+  review: "pending"
+  generate: "pending"
+  validate: "pending"
+
+# Auto-populated by factory during guided mode
+decisions: []
+
+# Post-completion metrics (factory populates after run)
+metrics:
+  discovery_path: null
+  hardest_step: null
+  would_use_again: null

package/_bmad/bme/_team-factory/workflows/add-team/step-01-scope.md

@@ -0,0 +1,105 @@
+# Step 01: Scope — Team Definition & Agent Inventory
+
+## Purpose
+Guide the contributor through defining their team's composition pattern, agents, and their roles. This is where architectural thinking happens — before any files are generated.
+
+## Prerequisites
+- Step 00 (Route) completed — contributor confirmed "Create Team"
+
+## Execution Sequence
+
+### 1. Team Identity
+
+Ask the contributor for:
+- **Team name** (human-readable, e.g., "Loom", "Gyre", "Sentinel")
+- **What does this team do?** (1-2 sentence description)
+- **Who uses it?** (target user persona)
+
+Derive `team_name_kebab` from the team name using naming conventions:
+- Lowercase, hyphens between words
+- Must match: `/^[a-z][a-z0-9]*(-[a-z0-9]+)*$/`
+- Confirm with contributor: "Your team module will be at `_bmad/bme/_{team_name_kebab}/`"
+
+### 2. Composition Pattern Selection
+
+Present the two patterns with plain-language descriptions and examples:
+
+> **Independent Pattern**
+> Agents operate standalone — each handles a separate concern. No handoff contracts between them.
+> _Think: a toolbox where each tool works on its own._
+> Example: A team with a "documentation auditor" and a "dependency checker" — related but independent tasks.
+>
+> **Sequential Pattern**
+> Agents form a pipeline — each one's output feeds the next. Handoff contracts define what gets passed.
+> _Think: an assembly line where each station adds something._
+> Examples: Vortex (7-agent discovery pipeline), Gyre (4-agent readiness analysis)
+
+**Default suggestion:** Based on the team description, suggest the most likely pattern with reasoning.
+
+**Cascade effect:** Once selected, the factory eliminates irrelevant decisions:
+- **Independent selected** → Skip: contract design, pipeline ordering, feedback contracts, contract prefix, compass routing (mark as optional)
+- **Sequential selected** → All decisions remain active
+
+Load cascade logic:
+```
+run: node -e "const c = require('{project-root}/_bmad/bme/_team-factory/lib/cascade-logic.js'); console.log(JSON.stringify(c.getCascadeForPattern('{pattern}'), null, 2))"
+expect: result.decisions → active decisions for this pattern
+        result.eliminated → decisions removed by pattern selection
+```
+
+### 3. Agent Inventory
+
+For each agent, collect:
+- **Agent ID** (kebab-case, e.g., `knowledge-surveyor`) — enforce: `/^[a-z]+(-[a-z]+)*$/`
+- **Display name** (first name persona, e.g., "Silo")
+- **Icon** (single emoji)
+- **Role** (what does this agent do — 1 sentence)
+- **Title** (formal title, e.g., "Knowledge Survey Specialist")
+- **Capabilities** (list of 2-5 key capabilities)
+- **Pipeline position** (Sequential only — integer, 1-based)
+
+Present agents one at a time. After each agent, ask: "Add another agent, or are you done?"
+
+**Naming enforcement per agent:**
+```
+run: node -e "const n = require('{project-root}/_bmad/bme/_team-factory/lib/utils/naming-utils.js'); const id = '{agent_id}'; console.log(JSON.stringify({ valid: /^[a-z]+(-[a-z]+)*$/.test(id), id }))"
+expect: result.valid === true → proceed
+        result.valid === false → "Agent ID must be lowercase letters and hyphens only (e.g., 'knowledge-surveyor'). Got: '{agent_id}'"
+```
+
+### 4. Overlap Detection
+
+After all agents are defined, run collision detection:
+```
+run: node -e "const cd = require('{project-root}/_bmad/bme/_team-factory/lib/collision-detector.js'); cd.detectCollisions({team_name_kebab: '{kebab}', agents: [{id: '{id1}'}, ...]}, '{project-root}/_bmad/_config/agent-manifest.csv', '{project-root}/_bmad/bme/').then(r => console.log(JSON.stringify(r, null, 2)))"
+expect: result.hasBlocking === false → proceed with optional warnings
+        result.hasBlocking === true → display blocks, ask contributor to rename
+        result.warnings.length > 0 → display warnings, ask contributor to acknowledge or rename
+```
+
+**Level 3 (LLM capability overlap):** After JS detection, review each agent's role and capabilities against the existing agent manifest. Flag potential functional overlaps:
+- "Your agent `{id}` with role '{role}' may overlap with existing agent `{existing_id}` ({existing_role}) in the {existing_module} module."
+- Ask: "Is this intentional? If so, I'll note the acknowledgment."
+
+### 5. Save Progress
+
+Initialize the spec file:
+- Create `team-spec-{team_name_kebab}.yaml` in `_bmad-output/planning-artifacts/`
+- Populate: team identity, composition pattern, agents, overlap acknowledgments
+- Set progress: `orient: complete, scope: complete, connect: pending, ...`
+
+Display: "Scope complete. {N} agents defined for team **{team_name}** ({pattern} pattern). Moving to integration design."
+
+Proceed to: `{project-root}/_bmad/bme/_team-factory/workflows/add-team/step-02-connect.md`
+
+## Visibility Checklist — Step 1
+Colleague sees:
+  - [ ] Team identity questions (name, description, users)
+  - [ ] Pattern selection with examples and recommendation
+  - [ ] Agent definition prompts (one at a time)
+Runs silently:
+  - [ ] Naming validation (per agent)
+  - [ ] Cascade logic (pattern → eliminated decisions)
+  - [ ] Collision detection (JS Level 1-2)
+Concept count: 3/3 (team identity, pattern, agents)
+Approval prompt: "Here's your team scope: {summary}. Ready to design integration?"

package/_bmad/bme/_team-factory/workflows/add-team/step-02-connect.md

@@ -0,0 +1,110 @@
+# Step 02: Connect — Integration Design
+
+## Purpose
+Guide the contributor through integration decisions: contracts (Sequential only), output directory, compass routing, and config field design. This step produces the integration section of the spec file.
+
+## Prerequisites
+- Step 01 (Scope) completed — team identity, pattern, and agents defined
+- Spec file exists with progress.scope = "complete"
+
+## Execution Sequence
+
+### 1. Load Context
+
+Read the spec file to get the team's composition pattern and agents.
+
+### 2. Contract Design (Sequential Only)
+
+> Skip this section entirely for Independent teams — cascade logic eliminated it.
+
+For Sequential teams, guide through handoff contract design:
+
+**Contract prefix:**
+- Ask: "What prefix should your contracts use? Examples: HC (Vortex), GC (Gyre). This prefix + number becomes the contract ID (e.g., HC1, HC2)."
+- Default suggestion based on team name initials
+
+**Forward contracts (required):**
+For each adjacent pair of agents in pipeline order:
+- "Agent **{source}** (position {N}) passes output to **{target}** (position {N+1})"
+- Ask for each contract:
+  - **Artifact title** — What is this artifact called?
+  - **Artifact description** — What does it contain? (1-2 sentences)
+  - **Key sections** — What are the main sections of this artifact?
+  - **File naming** — Default: `{prefix}{N}-{artifact-kebab}.md`
+
+Present each contract for confirmation before moving to the next.
+
+**Feedback contracts (optional):**
+- "Does any downstream agent need to send structured feedback back upstream?"
+- If yes: guide through the same contract template
+- If no: skip — "No feedback contracts. You can add them later."
+
+**Contract validation (B-lite semantic check):**
+For each contract, verify:
+- Source agent exists in the agent list
+- Target agent(s) exist in the agent list
+- No duplicate contract IDs
+
+### 3. Output Directory
+
+- Default: `_bmad-output/{team_name_kebab}-artifacts`
+- Ask: "Where should your team's output artifacts be saved?"
+- Validate: path should start with `_bmad-output/`
+
+### 4. Compass Routing
+
+**Sequential teams:**
+- Required. "Your team needs a compass routing reference — a navigation table that helps users know what to do next after each workflow."
+- Default: `shared-reference` (single file, like Vortex's `compass-routing-reference.md`)
+
+**Independent teams:**
+- Optional. "Would you like per-agent compass routing? This is optional for Independent teams since agents operate standalone."
+- Default: `per-agent` or `optional`
+
+### 5. Config Field Review
+
+Summarize what will go into the team's `config.yaml`:
+```
+submodule_name: _{team_name_kebab}
+description: {description}
+module: bme
+output_folder: '{project-root}/{output_directory}'
+agents: [{agent_ids}]
+workflows: [{workflow_names}]
+version: 1.0.0
+user_name: '{user}'
+communication_language: en
+party_mode_enabled: true
+core_module: bme
+```
+
+Run config field collision detection:
+```
+run: node -e "const cc = require('{project-root}/_bmad/bme/_team-factory/lib/writers/config-creator.js'); // collision check logic"
+expect: no collisions with existing config fields
+```
+
+### 6. Save Progress
+
+Update the spec file:
+- Add contracts, feedback_contracts, integration section
+- Set progress: `connect: complete`
+
+Display summary:
+- "{N} forward contracts, {M} feedback contracts defined" (Sequential)
+- "Output: {output_directory}, Compass routing: {routing_mode}"
+- "Moving to decision review."
+
+Proceed to: `{project-root}/_bmad/bme/_team-factory/workflows/add-team/step-03-review.md`
+
+## Visibility Checklist — Step 2
+Colleague sees:
+  - [ ] Contract design prompts (Sequential only, one at a time)
+  - [ ] Output directory confirmation
+  - [ ] Config field summary
+Runs silently:
+  - [ ] Contract validation (source/target exist, no duplicate IDs)
+  - [ ] Config field collision detection
+  - [ ] Cascade elimination check (contracts skipped for Independent)
+Concept count: 2/3 (contracts, integration settings) — or 1/3 for Independent (integration only)
+Approval prompt: "Integration design complete. Ready for the full decision review?"

package/_bmad/bme/_team-factory/workflows/add-team/step-03-review.md

@@ -0,0 +1,116 @@
+# Step 03: Review — Decision Summary & Approval
+
+## Purpose
+Present all decisions for contributor approval before generation begins. In Express Mode, this step is the full validation gate — all per-step and semantic checks run in batch.
+
+## Prerequisites
+- Step 02 (Connect) completed — all decisions made
+- Spec file has progress.connect = "complete"
+
+## Execution Sequence
+
+### 1. Load Spec
+
+Read the complete spec file. This is the ground truth for all decisions.
+
+### 2. Decision Summary
+
+Present a structured summary of all decisions made:
+
+```
+═══════════════════════════════════════════════════
+  TEAM FACTORY — Decision Summary
+═══════════════════════════════════════════════════
+
+  Team:        {team_name} (_{team_name_kebab})
+  Pattern:     {composition_pattern}
+  Module:      _bmad/bme/_{team_name_kebab}/
+
+  AGENTS ({count}):
+  ┌─────┬──────────────────────┬──────┬─────────────────────────┐
+  │ Pos │ ID                   │ Icon │ Role                    │
+  ├─────┼──────────────────────┼──────┼─────────────────────────┤
+  │  1  │ {agent_id}           │ {ic} │ {role}                  │
+  └─────┴──────────────────────┴──────┴─────────────────────────┘
+
+  CONTRACTS ({count}):            [Sequential only]
+  {prefix}{N}: {source} → {target} — "{artifact_title}"
+
+  FEEDBACK CONTRACTS ({count}):   [Sequential only]
+  {prefix}{N}: {source} → {target} — "{artifact_title}"
+
+  INTEGRATION:
+  Output:     {output_directory}
+  Routing:    {compass_routing}
+  Prefix:     {contract_prefix}            [Sequential only]
+
+  OVERLAP ACKNOWLEDGMENTS ({count}):
+  {agent_id} ↔ {existing_id}: acknowledged
+
+═══════════════════════════════════════════════════
+```
+
+### 3. Validation Gate (All Modes)
+
+Run all per-step validations in batch against the spec file:
+
+**Naming validation:**
+- team_name_kebab matches `/^[a-z][a-z0-9]*(-[a-z0-9]+)*$/`
+- All agent IDs match `/^[a-z]+(-[a-z]+)*$/`
+
+**Pattern validation:**
+- Composition pattern is "Independent" or "Sequential"
+- Sequential teams have contracts and contract_prefix
+- Independent teams have no contracts
+
+**Semantic validation (B-lite):**
+- All contract source_agents exist in agents list
+- All contract target_agents exist in agents list
+- No duplicate contract IDs
+- Pipeline positions are sequential (Sequential only)
+
+**Collision re-check:**
+- Run collision detector again (working tree may have changed since Step 01)
+
+Display validation results:
+- "✅ All {N} checks passed" or
+- "❌ {N} issues found:" followed by each issue with explanation
+
+### 4. Contributor Approval
+
+Ask explicitly:
+> "All decisions above will be used to generate your team. Would you like to:
+> 1. **Approve** — proceed to generation
+> 2. **Edit** — go back and change specific decisions
+> 3. **Save & Exit** — save the spec file and resume later"
+
+**If Edit:** Ask which section to change, update the spec file, re-display summary.
+**If Save & Exit:** Ensure progress.review = "pending" (so re-entry returns here), display spec file path.
+**If Approve:** Set progress.review = "complete", proceed.
+
+### 5. Express Mode Behavior
+
+In Express Mode (spec file loaded directly):
+- Skip to this step with all decisions pre-loaded
+- Run the full validation gate
+- If all checks pass: display summary, ask for approval
+- If checks fail: display errors, ask contributor to fix the spec file and re-run
+
+### 6. Save Progress
+
+Update spec file: progress.review = "complete"
+
+Proceed to: `{project-root}/_bmad/bme/_team-factory/workflows/add-team/step-04-generate.md`
+
+## Visibility Checklist — Step 3
+Colleague sees:
+  - [ ] Complete decision summary table
+  - [ ] Validation results (pass/fail)
+  - [ ] Approve/Edit/Save choice
+Runs silently:
+  - [ ] Naming validation batch
+  - [ ] Pattern validation
+  - [ ] Semantic validation (B-lite)
+  - [ ] Collision re-check
+Concept count: 1/3 (decision review — everything else is summary of prior decisions)
+Approval prompt: "Approve these decisions and proceed to file generation?"