convoke-agents 2.3.1 → 3.0.0

package/_bmad/bme/_enhance/workflows/initiatives-backlog/templates/backlog-format-spec.md

@@ -0,0 +1,219 @@
+# Backlog Format Specification
+
+Reference document for consistent backlog file formatting across all initiatives backlog operations. Loaded by the workflow during file write operations to ensure output matches the canonical format.
+
+All output must be standard markdown — no proprietary extensions, HTML embeds, or tool-specific syntax (NFR6).
+
+---
+
+## Metadata Header
+
+Every backlog file begins with:
+
+```markdown
+# Convoke Initiatives Backlog
+
+**Created:** YYYY-MM-DD
+**Method:** RICE (Reach, Impact, Confidence, Effort)
+**Last Updated:** YYYY-MM-DD
+```
+
+The `Last Updated` date is refreshed on every write operation.
+
+---
+
+## Section Hierarchy
+
+The backlog file uses this exact heading structure. Sections must appear in this order.
+
+```
+# Convoke Initiatives Backlog                    (H1 — title)
+
+## RICE Scoring Guide                            (H2 — inline scoring reference)
+
+## Backlog                                       (H2 — active items container)
+### [Category Name]                              (H3 — one per category, repeating)
+
+## Exploration Candidates                        (H2 — unscored items needing discovery)
+
+## Epic Groupings                                (H2 — bundled delivery suggestions)
+### Epic: "[Name]" ([item IDs])                  (H3 — one per grouping)
+
+## Prioritized View (by RICE Score)              (H2 — auto-generated ranked table)
+
+## Completed                                     (H2 — finished items, grouped by date)
+### YYYY-MM-DD                                   (H3 — date grouping for milestones)
+
+## Change Log                                    (H2 — operational history)
+```
+
+### Category Names
+
+Categories are user-defined H3 headings under `## Backlog`. The existing backlog uses:
+
+- Documentation & Onboarding
+- Update & Migration System
+- Testing & CI
+- Infrastructure
+- Agent Quality & Consistency
+- Platform & Product Vision
+
+New categories may be added. Category names must be unique within the backlog.
+
+---
+
+## Table Formats
+
+### Category Table (under each H3 category)
+
+```markdown
+| # | Initiative | Source | R | I | C | E | Score | Track | Status |
+|---|-----------|--------|---|---|---|---|-------|-------|--------|
+```
+
+**Column rules:**
+- `#`: Short alphanumeric ID (e.g., D2, P4, T3). Unique within the backlog.
+- `Initiative`: `**[Bold title]** — [description]`. May include markdown links.
+- `Source`: Origin of the initiative (e.g., "Vortex review (Liam, Wade)", "Product owner")
+- `R`: Reach score (integer 1-10)
+- `I`: Impact score (0.25, 0.5, 1, 2, or 3)
+- `C`: Confidence as percentage (e.g., 70%, 90%)
+- `E`: Effort score (integer 1-10)
+- `Score`: Composite RICE score, one decimal place (e.g., 2.8)
+- `Track`: "Keep the lights on" or "Move the needle"
+- `Status`: One of: Backlog, In Planning, In Progress, Done, Blocked
+
+### Prioritized View Table (under `## Prioritized View`)
+
+```markdown
+| Rank | # | Initiative | Score | Track | Category |
+|------|---|-----------|-------|-------|----------|
+```
+
+**Rules:**
+- Sorted by composite RICE score, descending
+- Tiebreak: Confidence (higher first), then insertion order (newer first)
+- Only includes active items (not Done or in Completed section)
+- Regenerated from scratch on every write operation — not manually maintained
+- Rank is a sequential integer starting at 1
+
+### Exploration Candidates Table (under `## Exploration Candidates`)
+
+```markdown
+| # | Initiative | Source | Next Step |
+|---|-----------|--------|-----------|
+```
+
+These items are unscored and not included in the prioritized view.
+
+### Completed Section Tables (under `## Completed`)
+
+Grouped by date using H3 headers:
+
+```markdown
+### YYYY-MM-DD
+
+| # | Initiative | Score | Category |
+|---|-----------|-------|----------|
+```
+
+**Note:** Legacy completed entries (pre-backlog era) may use non-standard table formats (e.g., `| Item | Fix Applied |`). These should be preserved as-is during write operations — do not attempt to reformat them.
+
+---
+
+## Change Log Format
+
+The Change Log section uses a table:
+
+```markdown
+## Change Log
+
+| Date | Change |
+|------|--------|
+| YYYY-MM-DD | [Description of what changed] |
+```
+
+Entries are prepended (newest first). Each workflow session adds one entry summarizing items added, removed, rescored, or moved.
+
+---
+
+## RICE Composite Formula
+
+**Formula:** Score = (Reach x Impact x Confidence) / Effort
+
+Where Confidence is expressed as a decimal (e.g., 70% = 0.7).
+
+**Example:** R:8, I:3, C:70%, E:6 = (8 x 3 x 0.7) / 6 = 2.8
+
+**Sort order:** Descending by composite score. Ties broken by:
+1. Confidence — higher first
+2. Insertion order — newer first
+
+---
+
+## Insertion Rules
+
+### Adding New Items (Triage mode, Create mode)
+
+1. Identify the target category H3 section under `## Backlog`
+2. Append the new row to the end of that category's table
+3. If the category doesn't exist, create a new H3 heading at the end of the `## Backlog` section (before `## Exploration Candidates`)
+4. Regenerate the `## Prioritized View` table with all active items sorted by composite score
+5. Add a Change Log entry
+
+### Moving Items to Completed
+
+1. Remove the item row from its category table
+2. Add it to the appropriate `### YYYY-MM-DD` group under `## Completed`
+3. If no group exists for today's date, create one
+4. Regenerate the `## Prioritized View` table
+5. Add a Change Log entry
+
+---
+
+## Provenance Tags
+
+Provenance is recorded in the Initiative cell description or as a separate annotation.
+
+### Triage Mode — New Items
+
+Format: `"Added from [source], [date]"`
+
+Example: `Added from party-mode review transcript, 2026-03-15`
+
+The score recorded is the **final** score after any Gate 2 user adjustments. The agent's initial proposal is not recorded separately. Triage Gate 2 adjustments are NOT rescores — they are the initial score. No rescore provenance is generated.
+
+### Review Mode — Rescored Items
+
+Format: `"Rescored [old]->[new], Review, [date]"`
+
+Example: `Rescored 1.8->2.4, Review, 2026-03-15`
+
+Only recorded when the composite score actually changes. Confirming an existing score or skipping an item generates no provenance entry.
+
+### Create Mode — New Items
+
+Format: `"Added from Create mode, [date]"`
+
+---
+
+## Pre-Write Validation
+
+Before writing to the backlog file, the workflow must validate:
+
+1. **Section heading anchors** — All required H2 sections exist in the correct order
+2. **Prioritized view table column count** — Table has exactly 6 columns
+3. **Category table column count** — Each category table has exactly 10 columns
+4. **Change Log section existence** — The Change Log H2 section exists
+5. **No data loss** — Existing category section content is preserved (no deletions, overwrites, or reordering of existing rows). The Prioritized View is excluded from this check since it is regenerated.
+
+If validation detects a structural mismatch, the user can proceed or abort.
+
+---
+
+## Format Consistency
+
+The backlog output must match the exact current format of `initiatives-backlog.md`. When in doubt, load the existing file and match its patterns precisely. This ensures:
+- Round-trip parseability (the workflow can reload its own output)
+- Manual editability (users can edit the file in any text editor between sessions)
+- `git diff` readability (consistent formatting minimizes noise)

package/_bmad/bme/_enhance/workflows/initiatives-backlog/templates/rice-scoring-guide.md

@@ -0,0 +1,154 @@
+# RICE Scoring Guide
+
+Reference document for consistent RICE scoring across all initiatives backlog operations. Loaded by the workflow during Triage (Gate 2 scoring), Review (rescoring), and Create (initial scoring) modes.
+
+---
+
+## RICE Factor Definitions
+
+| Factor | Scale | Description |
+|--------|-------|-------------|
+| **Reach** | 1-10 | How many users/quarter will this affect? (10 = all users, 1 = edge case) |
+| **Impact** | 0.25 - 3 | Per-user impact (3 = massive, 2 = high, 1 = medium, 0.5 = low, 0.25 = minimal) |
+| **Confidence** | 20-100% | How sure are we about reach and impact estimates? |
+| **Effort** | 1-10 | Relative effort in story points (1 = trivial, 10 = multi-epic) |
+| **Score** | calculated | (Reach x Impact x Confidence) / Effort |
+
+---
+
+## Guided Scoring Questions
+
+Use these questions to guide scoring for each factor. The goal is genuine strategic reflection, not mechanical calculation.
+
+### Reach (1-10)
+
+"How many users per quarter will this affect?"
+
+| Score | Meaning |
+|-------|---------|
+| 10 | All users — every project that installs Convoke encounters this |
+| 7-9 | Most users — affects a common workflow or visible surface |
+| 4-6 | Some users — affects a specific use case or user segment |
+| 2-3 | Few users — niche scenario or advanced feature |
+| 1 | Edge case — rare configuration or exceptional circumstance |
+
+### Impact (0.25-3)
+
+"What's the per-user impact when they encounter this?"
+
+| Score | Meaning | Signal |
+|-------|---------|--------|
+| 3 | Massive | Unblocks a capability that didn't exist before; users would pay for this |
+| 2 | High | Significant improvement to an existing workflow; saves meaningful time |
+| 1 | Medium | Noticeable improvement; users appreciate it but can work around it |
+| 0.5 | Low | Minor quality-of-life improvement; polish |
+| 0.25 | Minimal | Cosmetic or hygienic; almost invisible to users |
+
+### Confidence (20-100%)
+
+"How confident are we in the Reach and Impact estimates?"
+
+| Score | Meaning | Basis |
+|-------|---------|-------|
+| 100% | Measured data | Direct observation, usage metrics, user reports |
+| 80% | Strong evidence | Multiple corroborating signals, team consensus |
+| 60% | Reasonable estimate | Single data point or strong analogy to similar work |
+| 50% | Educated guess | Logical reasoning without direct evidence |
+| 40% | Informed speculation | Based on domain knowledge, no project-specific data |
+| 20% | Pure speculation | Gut feeling, novel territory, no precedent |
+
+### Effort (1-10)
+
+"Relative effort in story points?"
+
+| Score | Meaning |
+|-------|---------|
+| 1 | Trivial — single file change, under 30 minutes |
+| 2-3 | Small — a few files, a focused session |
+| 4-5 | Medium — multi-file, requires design thought, 1-2 stories |
+| 6-7 | Large — multi-story, cross-cutting concerns |
+| 8-9 | Very large — full epic, significant architecture work |
+| 10 | Multi-epic — major initiative spanning multiple sprints |
+
+---
+
+## Composite Formula & Sort Order
+
+**Formula:** Score = (Reach x Impact x Confidence) / Effort
+
+**Sort order:** Descending by composite score.
+
+**Tiebreak rules:**
+1. Higher Confidence first (more certain items surface above speculative ones)
+2. Newer insertion order first (recently added items break remaining ties)
+
+---
+
+## Calibration Examples
+
+These examples are drawn from the existing Convoke backlog to anchor scoring consistency. Study the reasoning, not just the numbers — the goal is to understand *why* items scored as they did.
+
+### Low Tier (~0.2-0.5)
+
+**A4: "Fix temp dir prefix inconsistency"** — R:1 I:0.25 C:100% E:1 = **0.3**
+- Reach 1: Only affects internal tooling, no user visibility
+- Impact 0.25: Cosmetic inconsistency with zero functional effect
+- Confidence 100%: Known, observable, deterministic
+- Effort 1: Single string change
+- *Lesson: High confidence and low effort don't rescue low reach and minimal impact*
+
+**A2: "Create .agent.yaml source files"** — R:2 I:0.5 C:60% E:4 = **0.2**
+- Reach 2: Only affects module authors using the BMAD authoring pipeline
+- Impact 0.5: Enables standard tooling but workarounds exist
+- Confidence 60%: Unclear how many authors will use the pipeline
+- Effort 4: Multiple files across multiple agents
+- *Lesson: Moderate effort with uncertain reach pushes score very low*
+
+### Medium Tier (~1.0-2.0)
+
+**U4: "Test upgrade-path step file cleanup"** — R:3 I:1 C:90% E:2 = **1.4**
+- Reach 3: Only users upgrading from specific older versions
+- Impact 1: Prevents a confusing stale-file scenario
+- Confidence 90%: Known issue from observed upgrade path
+- Effort 2: Focused integration test
+- *Lesson: High confidence on a real (but narrow) problem scores solidly mid-range*
+
+**I1: "NPM_TOKEN secret for CI publish"** — R:8 I:2 C:90% E:8 = **1.8**
+- Reach 8: Every release depends on this automation
+- Impact 2: Eliminates manual publish step, significant time savings
+- Confidence 90%: Well-understood CI pattern
+- Effort 8: Full CI pipeline setup, secrets management, testing
+- *Lesson: High reach and impact can be offset by high effort — the formula balances ambition against cost*
+
+### High Tier (~2.5+)
+
+**P4: "Enhance module"** — R:8 I:3 C:70% E:6 = **2.8**
+- Reach 8: New capability for every BMAD user with Convoke
+- Impact 3: Creates an entirely new value layer (multiplicative, not additive)
+- Confidence 70%: Architecture validated but user adoption uncertain
+- Effort 6: Multi-epic initiative with installer integration
+- *Lesson: Massive impact with broad reach justifies investment even at moderate confidence*
+
+**S4: "Skills migration & module compliance"** — R:10 I:2 C:90% E:5 = **3.6**
+- Reach 10: Affects every user — skills activation was broken
+- Impact 2: Restores core functionality and modernizes format
+- Confidence 90%: Known breakage with clear fix path
+- Effort 5: Multi-file migration with schema changes
+- *Lesson: Universal reach with a clear fix and high confidence produces the highest scores*
+
+---
+
+## Score Distribution Health Check
+
+A healthy backlog has differentiated scores. If more than 3 items share the same composite score in the top 10 of the prioritized view, refine the distinguishing RICE components — typically Confidence or Impact have the most room for differentiation.
+
+This is a quality signal, not a hard rule. Identical scores indicate either genuine parity (acceptable if rare) or insufficient scoring granularity (fix by re-examining the items with fresh eyes).
+
+---
+
+## Scoring Consistency Notes
+
+- Scores in this backlog range from approximately 0.2 to 10.0. New scores should land within this range.
+- Composite scores are rounded to one decimal place for display (e.g., 1.35 rounds to 1.4). This matches existing backlog convention and keeps the prioritized view scannable.
+- When scoring a new item, mentally compare it to 2-3 existing items at similar scale. If your proposed score would rank it significantly above or below where it "feels" relative to those items, revisit the component scores.
+- The Confidence factor is the most commonly under-scrutinized. Default to 50% (educated guess) when no direct evidence exists, not 80%.

package/_bmad/bme/_enhance/workflows/initiatives-backlog/workflow.md

@@ -0,0 +1,88 @@
+---
+workflow: initiatives-backlog
+type: step-file
+description: Tri-modal RICE initiatives backlog management — Triage review findings, Review existing items, or Create a new backlog from scratch
+author: John PM (pm.md)
+version: 1.0.0
+---
+
+# Initiatives Backlog Workflow
+
+Manage a RICE-scored initiatives backlog through three complementary modes. This workflow transforms unstructured review findings, audit outputs, and team discussions into prioritized, scored backlog items — and keeps them calibrated over time.
+
+## Workflow Structure
+
+**Step-file architecture:**
+- Just-in-time loading (each step loads only when needed)
+- Sequential enforcement within each mode
+- State tracking in frontmatter (progress preserved across sessions)
+- Two-gate validation in Triage mode (extraction review, then scoring review)
+
+## Modes Overview
+
+### [T] Triage — Ingest Review Findings
+Accepts text input (review transcripts, meeting notes, audit outputs), extracts actionable findings, proposes RICE scores with two-gate validation, and appends scored items to the existing backlog.
+- **Steps:** Ingest > Extract & Gate 1 > Score & Gate 2 > Update backlog
+- **When to use:** After a party-mode review, code review, retrospective, or any session that produces findings
+
+### [R] Review — Rescore Existing Items
+Loads the current backlog and walks through items for rescoring. Prevents score drift by prompting reassessment of Reach, Impact, Confidence, and Effort as project context evolves.
+- **Steps:** Load backlog > Walkthrough & rescore > Update backlog
+- **When to use:** Periodically (monthly or after major project milestones) to keep priorities calibrated
+
+### [C] Create — Build New Backlog
+Bootstraps a new RICE-scored backlog from scratch through guided interactive gathering and scoring.
+- **Steps:** Initialize > Gather initiatives > Score > Generate prioritized view
+- **When to use:** Starting a new project or creating a fresh backlog for a new domain
+
+## Output
+
+**Artifact:** `{planning_artifacts}/initiatives-backlog.md`
+**Templates:** `templates/rice-scoring-guide.md`, `templates/backlog-format-spec.md`
+
+---
+
+## INITIALIZATION
+
+Load config from `{project-root}/_bmad/bme/_enhance/config.yaml`
+
+## MODE SELECTION
+
+Display the following menu to the user:
+
+---
+
+**Initiatives Backlog — Select a Mode:**
+
+- **[T] Triage** — Ingest review findings into scored backlog items
+- **[R] Review** — Rescore existing backlog items to keep priorities calibrated
+- **[C] Create** — Bootstrap a new RICE-scored backlog from scratch
+- **[X] Exit** — Return to John PM agent menu
+
+---
+
+**ALWAYS halt and wait for user input after presenting the menu.**
+
+### Menu Handling Logic:
+
+- **IF T:** Load, read the entire file, and execute `{project-root}/_bmad/bme/_enhance/workflows/initiatives-backlog/steps-t/step-t-01-ingest.md`
+- **IF R:** Load, read the entire file, and execute `{project-root}/_bmad/bme/_enhance/workflows/initiatives-backlog/steps-r/step-r-01-load.md`
+- **IF C:** Load, read the entire file, and execute `{project-root}/_bmad/bme/_enhance/workflows/initiatives-backlog/steps-c/step-c-01-init.md`
+- **IF X:** Display "Exiting Initiatives Backlog workflow." and end the workflow — return control to the John PM agent menu
+- **IF any other input:** Display "Unknown option. Please select **T**, **R**, **C**, or **X**." then redisplay the Mode Selection menu above
+
+### EXECUTION RULES:
+
+- ALWAYS halt and wait for user input after presenting the menu
+- Do NOT auto-select a mode — the user must explicitly choose (ADR-3)
+- Modes run independently — do NOT switch modes mid-execution (ADR-4)
+- After X, end the workflow completely
+
+---
+
+<!-- RETURN-TO-MENU CONVENTION (for step file authors):
+     When the final step of any mode completes (e.g., step-t-04-update.md for Triage),
+     it must instruct the LLM to re-load this entire workflow file:
+     {project-root}/_bmad/bme/_enhance/workflows/initiatives-backlog/workflow.md
+     This re-presents the INITIALIZATION section and Mode Selection menu,
+     allowing the user to run another mode or exit (FR28). -->

package/_bmad/bme/_gyre/README.md

@@ -0,0 +1,100 @@
+# Gyre Pattern Module
+
+Technical inventory for the `_bmad/bme/_gyre` module — production readiness discovery through stack analysis, contextual model generation, and absence detection. Gyre analyzes your codebase to find what's missing before you ship.
+
+## Agents (4)
+
+| # | Agent | ID | Icon | Role | File |
+|---|-------|----|------|------|------|
+| 1 | Scout | `stack-detective` | 🔎 | Stack Detection | `agents/stack-detective.md` |
+| 2 | Atlas | `model-curator` | 📐 | Model Generation | `agents/model-curator.md` |
+| 3 | Lens | `readiness-analyst` | 🔬 | Readiness Analysis | `agents/readiness-analyst.md` |
+| 4 | Coach | `review-coach` | 🏋️ | Review & Feedback | `agents/review-coach.md` |
+
+**Registry:** `scripts/update/lib/agent-registry.js` (single source of truth)
+
+## Workflows (7)
+
+### Scout — Stack Detection (1 workflow)
+| Workflow | Directory |
+|----------|-----------|
+| `stack-detection` | `workflows/stack-detection/` |
+
+### Atlas — Model Generation (1 workflow)
+| Workflow | Directory |
+|----------|-----------|
+| `model-generation` | `workflows/model-generation/` |
+
+### Lens — Readiness Analysis (2 workflows)
+| Workflow | Directory |
+|----------|-----------|
+| `gap-analysis` | `workflows/gap-analysis/` |
+| `delta-report` | `workflows/delta-report/` |
+
+### Coach — Review (1 workflow)
+| Workflow | Directory |
+|----------|-----------|
+| `model-review` | `workflows/model-review/` |
+
+### Orchestration (1 workflow)
+| Workflow | Directory |
+|----------|-----------|
+| `full-analysis` | `workflows/full-analysis/` |
+
+### Validation (1 workflow)
+| Workflow | Directory |
+|----------|-----------|
+| `accuracy-validation` | `workflows/accuracy-validation/` |
+
+## Handoff Contracts (4)
+
+### Artifact Contracts (GC1-GC3) — schema files in `contracts/`
+| Contract | Flow | Schema |
+|----------|------|--------|
+| GC1 | Scout → Atlas, Lens | `contracts/gc1-stack-profile.md` |
+| GC2 | Atlas → Lens, Coach | `contracts/gc2-capabilities-manifest.md` |
+| GC3 | Lens → Coach | `contracts/gc3-findings-report.md` |
+
+### Feedback Contract (GC4) — amendment loop
+| Contract | Flow | Schema |
+|----------|------|--------|
+| GC4 | Coach → Atlas | `contracts/gc4-feedback-loop.md` |
+
+## File Structure
+
+```
+_bmad/bme/_gyre/
+├── README.md                            # This file
+├── config.yaml                          # Module configuration
+├── compass-routing-reference.md         # Complete routing tables
+├── agents/
+│   ├── stack-detective.md               # Scout 🔎
+│   ├── model-curator.md                 # Atlas 📐
+│   ├── readiness-analyst.md             # Lens 🔬
+│   └── review-coach.md                  # Coach 🏋️
+├── contracts/
+│   ├── gc1-stack-profile.md             # Stack Profile artifact schema
+│   ├── gc2-capabilities-manifest.md     # Capabilities Manifest schema
+│   ├── gc3-findings-report.md           # Findings Report schema
+│   └── gc4-feedback-loop.md             # Feedback Loop schema
+└── workflows/
+    ├── full-analysis/                   # Orchestrator (all agents)
+    ├── stack-detection/                 # Scout
+    ├── model-generation/                # Atlas
+    ├── model-review/                    # Coach
+    ├── gap-analysis/                    # Lens
+    ├── delta-report/                    # Lens
+    └── accuracy-validation/             # Atlas (spike/validation)
+```
+
+## Output Artifacts
+
+Gyre writes its artifacts to `_bmad-output/gyre-artifacts/`:
+
+| Artifact | Format | Producer |
+|----------|--------|----------|
+| Stack Profile | `.gyre/stack-profile.yaml` | Scout (GC1) |
+| Capabilities Manifest | `.gyre/capabilities.yaml` | Atlas (GC2) |
+| Findings Report | `.gyre/findings.yaml` | Lens (GC3) |
+| Feedback Log | `.gyre/feedback.yaml` | Coach (GC4) |
+| Delta Report | `.gyre/delta-report.yaml` | Lens |