convoke-agents 3.2.1 → 3.3.0

package/scripts/update/lib/changelog-reader.js

@@ -0,0 +1,90 @@
+'use strict';
+
+const fs = require('fs');
+const path = require('path');
+const { compareVersions } = require('./utils');
+
+const DEFAULT_CHANGELOG_PATH = path.join(__dirname, '..', '..', '..', 'CHANGELOG.md');
+
+// Broad bracket-capture so pre-release headers ([1.0.4-alpha]) don't get skipped —
+// a skipped header would leak its body into the preceding entry. Non-semver labels
+// (Unreleased, TBD) are dropped later by SEMVER_RE. Date may use ASCII or en/em dash.
+const HEADER_RE = /^##\s+\[([^\]]+)\](?:\s*[-–—]\s*(.+?))?\s*$/;
+const SEMVER_RE = /^\d+\.\d+\.\d+(?:[-+][\w.-]+)?$/;
+const FENCE_RE = /^(?:```|~~~)/;
+
+/**
+ * Parse a Keep-a-Changelog-formatted file and return entries for versions
+ * strictly greater than `fromVersion` and less than or equal to `toVersion`.
+ *
+ * Returns entries newest-first. Unreleased sections, malformed headers, and
+ * missing files are skipped silently — this is a decorative surface and must
+ * never break the update flow.
+ *
+ * @param {string|null|undefined} fromVersion - Installed version (exclusive lower bound). Null treats all entries <= toVersion as new.
+ * @param {string} toVersion - Target version (inclusive upper bound).
+ * @param {string} [changelogPath] - Absolute path to CHANGELOG.md.
+ * @returns {Array<{version: string, date: string|null, body: string}>}
+ */
+function readChangelogEntries(fromVersion, toVersion, changelogPath = DEFAULT_CHANGELOG_PATH) {
+  if (!toVersion) return [];
+
+  let raw;
+  try {
+    raw = fs.readFileSync(changelogPath, 'utf8');
+  } catch {
+    return [];
+  }
+
+  const entries = [];
+  const lines = raw.split('\n');
+  let current = null;
+  let inFence = false;
+
+  const flush = () => {
+    if (!current) return;
+    current.body = current.bodyLines.join('\n').replace(/\s+$/, '');
+    delete current.bodyLines;
+    entries.push(current);
+    current = null;
+  };
+
+  for (const line of lines) {
+    if (FENCE_RE.test(line)) {
+      inFence = !inFence;
+      if (current) current.bodyLines.push(line);
+      continue;
+    }
+    if (!inFence) {
+      const match = HEADER_RE.exec(line);
+      if (match) {
+        flush();
+        current = {
+          version: match[1].trim(),
+          date: match[2] ? match[2].trim() : null,
+          bodyLines: [],
+        };
+        continue;
+      }
+    }
+    if (current) {
+      if (!inFence && /^---\s*$/.test(line)) continue;
+      current.bodyLines.push(line);
+    }
+  }
+  flush();
+
+  return entries
+    .filter((e) => {
+      if (!SEMVER_RE.test(e.version)) return false;
+      const aboveFloor = fromVersion ? compareVersions(e.version, fromVersion) > 0 : true;
+      const atOrBelowCeiling = compareVersions(e.version, toVersion) <= 0;
+      return aboveFloor && atOrBelowCeiling;
+    })
+    .sort((a, b) => compareVersions(b.version, a.version));
+}
+
+module.exports = {
+  readChangelogEntries,
+  DEFAULT_CHANGELOG_PATH,
+};

package/scripts/update/lib/config-merger.js

@@ -19,6 +19,40 @@ const { assertVersion } = require('./utils');
 
 const MERGED_DOC_SENTINEL = Symbol.for('convoke.config-merger.docMerged');
 
+/**
+ * Read `excluded_agents` from a module's config.yaml without going through the
+ * full merge path. Used by refresh-installation and validator to skip copying
+ * / checking agents the operator has opted out of. U8: permanent agent
+ * exclusions that survive upgrades.
+ *
+ * @param {string} configPath - Absolute path to module config.yaml
+ * @returns {string[]} Array of excluded agent IDs (empty if missing, malformed, or not an array)
+ */
+function readExcludedAgents(configPath) {
+  let content;
+  try {
+    content = fs.readFileSync(configPath, 'utf8');
+  } catch (err) {
+    // ENOENT is expected on fresh installs (config hasn't been written yet).
+    // Other IO errors (EACCES, EISDIR, EMFILE, ...) indicate a real misconfiguration —
+    // warn so the operator knows their exclusions won't be applied this run. Never throw:
+    // this reader must not break the install flow.
+    if (err && err.code !== 'ENOENT') {
+      console.warn(`Warning: could not read ${configPath} for excluded_agents (${err.code || err.message}). Proceeding without exclusions.`);
+    }
+    return [];
+  }
+  try {
+    const parsed = yaml.load(content);
+    if (parsed && Array.isArray(parsed.excluded_agents)) {
+      return parsed.excluded_agents.filter(a => typeof a === 'string');
+    }
+  } catch (err) {
+    console.warn(`Warning: could not parse ${configPath} for excluded_agents (${err.message}). Proceeding without exclusions.`);
+  }
+  return [];
+}
+
 /**
  * Merge current config with new template while preserving user preferences.
  * Agents and workflows use smart-merge: canonical entries in registry order
@@ -78,13 +112,29 @@ async function mergeConfig(currentConfigPath, newVersion, updates = {}) {
 
   // Smart-merge agents: canonical agents in order, then unique user-added agents appended.
   // Core agents are always restored to canonical order. User-added agents (not in AGENT_IDS)
-  // are preserved and deduplicated. Deliberately removed core agents are restored on upgrade.
+  // are preserved and deduplicated.
+  //
+  // U8: respect `excluded_agents` — an operator-maintained opt-out list. Agents named in that
+  // list are filtered out of the active `agents` array so deliberate removals survive upgrades.
+  // Re-inclusion works by removing the agent from `excluded_agents` — the next merge restores
+  // it via the canonical spread above.
+  const excludedAgents = Array.isArray(current.excluded_agents)
+    ? current.excluded_agents.filter(a => typeof a === 'string')
+    : [];
   if (updates.agents) {
     const userAgents = Array.isArray(current.agents)
       ? [...new Set(current.agents.filter(a => !AGENT_IDS.includes(a)))]
       : [];
     merged.agents = [...updates.agents, ...userAgents];
   }
+  // Apply exclusions to merged.agents regardless of whether `updates.agents` was provided —
+  // otherwise callers that pass empty updates (e.g., a workflows-only migration delta) would
+  // leak excluded agents back via the `defaults` spread at line 96.
+  if (excludedAgents.length > 0 && Array.isArray(merged.agents)) {
+    merged.agents = merged.agents.filter(a => !excludedAgents.includes(a));
+  }
+  // Preserve the exclusion list as a first-class field (empty stays empty — the schema default).
+  merged.excluded_agents = excludedAgents;
 
   // Smart-merge workflows: canonical workflows in order, then unique user-added appended
   if (updates.workflows) {
@@ -365,6 +415,7 @@ function addMigrationHistory(config, fromVersion, toVersion, migrationsApplied)
 module.exports = {
   CONFIG_SCHEMA,
   mergeConfig,
+  readExcludedAgents,
   extractUserPreferences,
   validateConfig,
   writeConfig,

package/scripts/update/lib/refresh-installation.js

@@ -6,7 +6,7 @@ const yaml = require('js-yaml');
 const YAML = require('yaml'); // Comment-preserving YAML library (ag-7-1: I29). Use for WRITE sites that need to preserve comments. js-yaml stays for read-only consumers.
 const { getPackageVersion, assertVersion } = require('./utils');
 const configMerger = require('./config-merger');
-const { AGENTS, AGENT_FILES, AGENT_IDS, WORKFLOW_NAMES, USER_GUIDES, GYRE_AGENTS, GYRE_AGENT_FILES, GYRE_AGENT_IDS, GYRE_WORKFLOW_NAMES, EXTRA_BME_AGENTS } = require('./agent-registry');
+const { AGENTS, AGENT_FILES, AGENT_IDS, WORKFLOW_NAMES, GYRE_AGENTS, GYRE_AGENT_FILES, GYRE_AGENT_IDS, GYRE_WORKFLOW_NAMES, EXTRA_BME_AGENTS } = require('./agent-registry');
 
 /**
  * Refresh Installation for Convoke
@@ -37,6 +37,15 @@ async function refreshInstallation(projectRoot, options = {}) {
   // source and destination are identical — skip file copies.
   const isSameRoot = path.resolve(packageRoot) === path.resolve(projectRoot);
 
+  // U8: read per-module `excluded_agents` from target configs BEFORE copy.
+  // These are opt-out lists the operator maintains; excluded agents don't get
+  // their agent file copied, don't get a skill wrapper generated, and don't
+  // fail presence checks downstream.
+  const vortexExcluded = configMerger.readExcludedAgents(path.join(targetVortex, 'config.yaml'));
+  const gyreExcluded = configMerger.readExcludedAgents(
+    path.join(projectRoot, '_bmad', 'bme', '_gyre', 'config.yaml')
+  );
+
   // 1. Copy agent files
   const agentsSource = path.join(packageVortex, 'agents');
   const agentsTarget = path.join(targetVortex, 'agents');
@@ -44,6 +53,12 @@ async function refreshInstallation(projectRoot, options = {}) {
 
   if (!isSameRoot) {
     for (const file of AGENT_FILES) {
+      const agentId = file.replace(/\.md$/, '');
+      if (vortexExcluded.includes(agentId)) {
+        changes.push(`Skipped excluded Vortex agent: ${file}`);
+        if (verbose) console.log(`    Skipped excluded Vortex agent: ${file}`);
+        continue;
+      }
       const src = path.join(agentsSource, file);
       if (fs.existsSync(src)) {
         await fs.copy(src, path.join(agentsTarget, file), { overwrite: true });
@@ -290,6 +305,12 @@ async function refreshInstallation(projectRoot, options = {}) {
 
     if (!isSameRoot) {
       for (const file of GYRE_AGENT_FILES) {
+        const agentId = file.replace(/\.md$/, '');
+        if (gyreExcluded.includes(agentId)) {
+          changes.push(`Skipped excluded Gyre agent: ${file}`);
+          if (verbose) console.log(`    Skipped excluded Gyre agent: ${file}`);
+          continue;
+        }
         const src = path.join(gyreAgentsSource, file);
         if (fs.existsSync(src)) {
           await fs.copy(src, path.join(gyreAgentsTarget, file), { overwrite: true });
@@ -502,17 +523,21 @@ async function refreshInstallation(projectRoot, options = {}) {
     ].map(csvEscape).join(',');
   }
 
+  // U8: filter out excluded agents so manifest rows don't point at wrappers the
+  // stale-cleanup loop (§6) just removed. Left in, rows become dangling pointers.
+  const activeVortexAgents = AGENTS.filter(a => !vortexExcluded.includes(a.id));
+  const activeGyreAgents = GYRE_AGENTS.filter(a => !gyreExcluded.includes(a.id));
   let bmeRows;
   if (isV610) {
     bmeRows = [
-      ...AGENTS.map(a => buildAgentRow610(a, '_vortex')),
-      ...GYRE_AGENTS.map(a => buildAgentRow610(a, '_gyre')),
+      ...activeVortexAgents.map(a => buildAgentRow610(a, '_vortex')),
+      ...activeGyreAgents.map(a => buildAgentRow610(a, '_gyre')),
       ...EXTRA_BME_AGENTS.map(buildExtraBmeAgentRow610),
     ];
   } else {
     bmeRows = [
-      ...AGENTS.map(a => buildAgentRowLegacy(a, '_vortex')),
-      ...GYRE_AGENTS.map(a => buildAgentRowLegacy(a, '_gyre')),
+      ...activeVortexAgents.map(a => buildAgentRowLegacy(a, '_vortex')),
+      ...activeGyreAgents.map(a => buildAgentRowLegacy(a, '_gyre')),
       ...EXTRA_BME_AGENTS.map(buildExtraBmeAgentRowLegacy),
     ];
   }
@@ -528,7 +553,16 @@ async function refreshInstallation(projectRoot, options = {}) {
   await fs.ensureDir(guidesTarget);
 
   if (!isSameRoot) {
-    for (const guide of USER_GUIDES) {
+    // U8: user guides are named after each agent (e.g., NOAH-USER-GUIDE.md). Iterate
+    // AGENTS so we can match guides to agent IDs and skip excluded ones — a guide
+    // without its agent is dead docs.
+    for (const agent of AGENTS) {
+      const guide = `${agent.name.toUpperCase()}-USER-GUIDE.md`;
+      if (vortexExcluded.includes(agent.id)) {
+        changes.push(`Skipped excluded guide: ${guide}`);
+        if (verbose) console.log(`    Skipped excluded guide: ${guide}`);
+        continue;
+      }
       const src = path.join(guidesSource, guide);
       const dest = path.join(guidesTarget, guide);
 
@@ -563,10 +597,13 @@ async function refreshInstallation(projectRoot, options = {}) {
 
   const skillsDir = path.join(projectRoot, '.claude', 'skills');
 
-  // Remove stale skill directories (agents no longer in registry)
+  // Remove stale skill directories (agents no longer in registry OR excluded by operator).
+  // U8: excluded agents are intentionally omitted from the valid set so the stale-removal
+  // loop below deletes their wrappers on the next refresh. Re-inclusion (removing from
+  // excluded_agents) regenerates the wrapper here.
   const currentSkillDirs = new Set([
-    ...AGENTS.map(a => `bmad-agent-bme-${a.id}`),
-    ...GYRE_AGENTS.map(a => `bmad-agent-bme-${a.id}`),
+    ...AGENTS.filter(a => !vortexExcluded.includes(a.id)).map(a => `bmad-agent-bme-${a.id}`),
+    ...GYRE_AGENTS.filter(a => !gyreExcluded.includes(a.id)).map(a => `bmad-agent-bme-${a.id}`),
     ...EXTRA_BME_AGENTS.map(a => `bmad-agent-bme-${a.id}`),
   ]);
   if (fs.existsSync(skillsDir)) {
@@ -581,6 +618,7 @@ async function refreshInstallation(projectRoot, options = {}) {
   }
 
   for (const agent of AGENTS) {
+    if (vortexExcluded.includes(agent.id)) continue;
     const skillDir = path.join(skillsDir, `bmad-agent-bme-${agent.id}`);
     await fs.ensureDir(skillDir);
     const content = `---
@@ -606,6 +644,7 @@ You must fully embody this agent's persona and follow all activation instruction
 
   // 6b. Generate .claude/skills/ for Gyre agents
   for (const agent of GYRE_AGENTS) {
+    if (gyreExcluded.includes(agent.id)) continue;
     const skillDir = path.join(skillsDir, `bmad-agent-bme-${agent.id}`);
     await fs.ensureDir(skillDir);
     const content = `---

package/scripts/update/lib/taxonomy-merger.js

@@ -11,7 +11,8 @@ const PLATFORM_INITIATIVES = ['vortex', 'gyre', 'bmm', 'forge', 'helm', 'enhance
 const DEFAULT_ARTIFACT_TYPES = [
   'prd', 'epic', 'arch', 'adr', 'persona', 'lean-persona', 'empathy-map',
   'problem-def', 'hypothesis', 'experiment', 'signal', 'decision', 'scope',
-  'pre-reg', 'sprint', 'brief', 'vision', 'report', 'research', 'story', 'spec'
+  'pre-reg', 'sprint', 'brief', 'vision', 'report', 'research', 'story', 'spec',
+  'covenant'
 ];
 
 const DEFAULT_ALIASES = {

package/scripts/update/lib/validator.js

@@ -111,7 +111,15 @@ async function validateAgentFiles(projectRoot) {
 
   try {
     const agentsDir = path.join(projectRoot, '_bmad/bme/_vortex/agents');
-    const requiredAgents = AGENT_FILES;
+    // U8: honor operator agent exclusions from the target config.yaml, so a
+    // deliberately-removed agent doesn't fail post-upgrade validation.
+    const configMerger = require('./config-merger');
+    const excluded = configMerger.readExcludedAgents(
+      path.join(projectRoot, '_bmad/bme/_vortex/config.yaml')
+    );
+    const requiredAgents = AGENT_FILES.filter(
+      f => !excluded.includes(f.replace(/\.md$/, ''))
+    );
 
     if (!fs.existsSync(agentsDir)) {
       check.error = 'agents/ directory not found';

package/_bmad/bme/_enhance/workflows/initiatives-backlog/steps-c/step-c-03-score.md

@@ -1,146 +0,0 @@
----
-name: 'step-c-03-score'
-description: 'Propose RICE scores for gathered initiatives in batch, validate with user, assign track labels'
-nextStepFile: '{project-root}/_bmad/bme/_enhance/workflows/initiatives-backlog/steps-c/step-c-04-prioritize.md'
-outputFile: '{planning_artifacts}/initiatives-backlog.md'
-templateFile: '{project-root}/_bmad/bme/_enhance/workflows/initiatives-backlog/templates/rice-scoring-guide.md'
-advancedElicitationTask: '{project-root}/_bmad/core/workflows/advanced-elicitation/workflow.md'
-partyModeWorkflow: '{project-root}/_bmad/core/workflows/bmad-party-mode/workflow.md'
----
-
-# Step 3: Batch RICE Scoring
-
-## STEP GOAL:
-
-Propose RICE scores and Track assignments for all gathered initiatives, present the scored batch for user validation, and finalize scores before backlog generation.
-
-## MANDATORY EXECUTION RULES (READ FIRST):
-
-### Universal Rules:
-- 🛑 NEVER generate content without user input at the scoring menu
-- 📖 CRITICAL: Read this complete step file before taking action
-- 🔄 CRITICAL: When loading next step with 'C', read the entire file
-- 📋 YOU ARE A SCORING ANALYST proposing calibrated RICE scores
-
-### Role Reinforcement:
-- ✅ You are a **RICE scoring analyst** — systematic, calibrated, evidence-based
-- ✅ Propose scores grounded in the scoring guide's definitions and calibration examples
-- ✅ The user validates and adjusts your proposals — you propose, they decide
-- ✅ Assign Track labels based on initiative nature: maintenance/stability = "Keep the lights on", growth/new capability = "Move the needle"
-
-### Step-Specific Rules:
-- 🎯 Focus on scoring, rationale, Track assignment, and composite calculation
-- 🚫 FORBIDDEN to write to the backlog file (that is step-c-04's job)
-- 🚫 FORBIDDEN to re-gather or add new initiatives (that was step-c-02's job)
-- 💬 Approach: propose entire batch at once so user sees relative positioning, then collaborative refinement
-
-## EXECUTION PROTOCOLS:
-- 🎯 Follow the MANDATORY SEQUENCE exactly
-- 📖 Load `{templateFile}` for RICE factor definitions, scales, and calibration examples
-- 💾 Recalculate and re-sort after every score adjustment
-
-## CONTEXT BOUNDARIES:
-- Available context: Gathered initiatives from step-c-02, RICE scoring guide template
-- Focus: Scoring and user validation only
-- Limits: Do NOT write to backlog or modify gathered initiative descriptions
-- Dependencies: step-c-02-gather.md (gathered initiatives list)
-
-## MANDATORY SEQUENCE
-
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
-
-### 1. Load RICE Scoring Guide
-
-Load `{templateFile}` (rice-scoring-guide.md) and internalize:
-- **Factor definitions:** Reach (1-10), Impact (0.25-3), Confidence (20-100%), Effort (1-10)
-- **Guided questions** for each factor
-- **Calibration examples** (study the reasoning, not just the numbers)
-- **Composite formula:** Score = (R x I x C) / E, where C is decimal (e.g., 70% = 0.7)
-- **Score rounding:** One decimal place for display
-
-### 2. Propose RICE Scores and Track for All Initiatives
-
-For each gathered initiative, propose RICE scores using the guided questions:
-
-- **Reach (1-10):** "How many users per quarter will this affect?"
-- **Impact (0.25-3):** "What's the per-user impact?"
-- **Confidence (20-100%):** "How confident are we in these estimates?" Default to 50% when no direct evidence exists.
-- **Effort (1-10):** "Relative effort in story points?"
-- **Track:** "Keep the lights on" (maintenance, stability, bug fixes) or "Move the needle" (growth, new capability, strategic)
-
-For each score, write a **one-line rationale** explaining the scoring basis. Example:
-
-> **#1: Add output examples for Noah agent** — R:5 I:1 C:70% E:2 = 1.8 | Move the needle
-> *Reach 5: affects users checking agent outputs. Impact 1: helpful but workarounds exist. Confidence 70%: pattern validated with other agents. Effort 2: single file addition.*
-
-### 3. Calculate Composite Scores and Sort
-
-For each initiative:
-1. Calculate composite: Score = (Reach x Impact x Confidence) / Effort
-2. Round to one decimal place
-3. Verify score falls within expected range (~0.0 to ~30.0)
-
-Sort the batch:
-1. **Primary:** Descending by composite score
-2. **Tiebreak 1:** Higher Confidence first
-3. **Tiebreak 2:** Newer insertion order first
-
-### 4. Present Scoring Batch
-
-Display the scored results:
-
-> **RICE Scoring — Review Proposed Scores**
->
-> **Initiatives scored: [N]**
->
-> | # | Initiative | R | I | C | E | Score | Track | Rationale |
-> |---|-----------|---|---|---|---|-------|-------|-----------|
-> | 1 | [title] | 5 | 2 | 80% | 3 | 2.7 | Move the needle | [one-line rationale] |
-> | 2 | [title] | 3 | 1 | 60% | 2 | 0.9 | Keep the lights on | [one-line rationale] |
->
-> *Sorted by composite score (descending). Formula: (R x I x C) / E*
-
-### 5. Present SCORING MENU OPTIONS
-
-Display:
-
-> **Adjust scores or finalize:**
->
-> **Score adjustments** (by item number):
-> - `#N R [value]` — Change Reach (1-10)
-> - `#N I [value]` — Change Impact (0.25, 0.5, 1, 2, or 3)
-> - `#N CF [value]` — Change Confidence (20-100%)
-> - `#N E [value]` — Change Effort (1-10)
-> - `#N T [value]` — Change Track ("keep" or "move")
->
-> **Batch editing:**
-> - `D #N` — Drop item #N from the batch (will not be added to backlog)
->
-> **[A] Advanced Elicitation** — Deeper analysis of scoring rationale
-> **[P] Party Mode** — Multi-perspective scoring discussion
-> **[C] Continue** — Finalize scores and proceed to backlog generation
-
-#### Menu Handling Logic:
-- IF `#N R [value]`: Update Reach for item #N. Recalculate composite. Re-sort batch. Redisplay table and menu.
-- IF `#N I [value]`: Update Impact for item #N. Recalculate composite. Re-sort batch. Redisplay table and menu.
-- IF `#N CF [value]`: Update Confidence for item #N. Recalculate composite. Re-sort batch. Redisplay table and menu.
-- IF `#N E [value]`: Update Effort for item #N. Recalculate composite. Re-sort batch. Redisplay table and menu.
-- IF `#N T [value]`: Update Track for item #N ("keep" = "Keep the lights on", "move" = "Move the needle"). Redisplay table and menu.
-- IF `D #N`: Remove item #N from the scoring batch. Redisplay table and menu.
-- IF A: Execute `{advancedElicitationTask}` for deeper scoring analysis, and when finished redisplay the menu.
-- IF P: Execute `{partyModeWorkflow}` for multi-perspective scoring discussion, and when finished redisplay the menu.
-- IF C: Finalize the scored batch. Load, read the entire file, and execute `{project-root}/_bmad/bme/_enhance/workflows/initiatives-backlog/steps-c/step-c-04-prioritize.md`
-- IF any other input: Display "Unknown command. Use `#N R/I/CF/E/T [value]`, `D #N`, **A**, **P**, or **C** to continue." then redisplay menu.
-
-#### EXECUTION RULES:
-- ALWAYS halt and wait for user input after presenting the menu
-- After EVERY score or Track adjustment, recalculate composite, re-sort, and redisplay the full table AND the menu
-- The user may make multiple adjustments before pressing C
-- ONLY proceed to step-c-04 when user selects 'C'
-- After A or P execution, return to this menu
-- Do NOT auto-continue — the user must explicitly approve the scores
-
-## 🚨 SYSTEM SUCCESS/FAILURE METRICS:
-### ✅ SUCCESS: All initiatives scored with calibrated RICE components, rationale, and Track assignment, composites calculated correctly, batch sorted by score, user validated scores, finalized batch passed to step-c-04
-### ❌ SYSTEM FAILURE: Scores proposed without rationale, composite formula wrong, Track not assigned, scores outside valid ranges, user not given validation opportunity, items written to backlog prematurely
-**Master Rule:** Skipping steps is FORBIDDEN.

package/_bmad/bme/_enhance/workflows/initiatives-backlog/steps-c/step-c-04-prioritize.md

@@ -1,181 +0,0 @@
----
-name: 'step-c-04-prioritize'
-description: 'Generate complete backlog file with categorized items, prioritized view, and completion summary'
-outputFile: '{planning_artifacts}/initiatives-backlog.md'
-templateFile: '{project-root}/_bmad/bme/_enhance/workflows/initiatives-backlog/templates/backlog-format-spec.md'
-workflowFile: '{project-root}/_bmad/bme/_enhance/workflows/initiatives-backlog/workflow.md'
----
-
-# Step 4: Backlog Generation, Prioritized View & Completion
-
-## STEP GOAL:
-
-Generate the complete backlog file from scratch using the scored initiatives, including all required sections, the prioritized view, provenance tags, and a changelog entry. Present a completion summary and return to the T/R/C menu.
-
-## MANDATORY EXECUTION RULES (READ FIRST):
-
-### Universal Rules:
-- 🛑 NEVER generate content without completing all mandatory sequence steps
-- 📖 CRITICAL: Read this complete step file before taking action
-- 🔄 CRITICAL: When returning to menu, read the entire workflow file
-- 📋 YOU ARE A BACKLOG OPERATIONS SPECIALIST generating a new backlog file
-
-### Role Reinforcement:
-- ✅ You are a **backlog operations specialist** — precise, structured, format-compliant
-- ✅ Generate the file exactly matching the backlog format specification — no shortcuts
-- ✅ All output must be standard markdown — no HTML, no proprietary syntax
-- ✅ Every item gets provenance, every section gets created, the prioritized view is sorted
-
-### Step-Specific Rules:
-- 🎯 Focus on file generation, provenance, prioritized view, and completion reporting
-- 🚫 FORBIDDEN to rescore items (scoring was finalized in step-c-03)
-- 🚫 FORBIDDEN to add new items not in the scored batch
-- 🚫 FORBIDDEN to modify step-c-01, step-c-02, or step-c-03
-- 💬 Approach: generate the complete file, summarize clearly, return to menu
-
-## EXECUTION PROTOCOLS:
-- 🎯 Follow the MANDATORY SEQUENCE exactly
-- 📖 Load `{templateFile}` (backlog-format-spec.md) for exact structural requirements and table formats
-- 💾 Write to `{outputFile}` as a complete new file
-
-## CONTEXT BOUNDARIES:
-- Available context: Scored initiatives from step-c-03, backlog format spec template
-- Focus: File generation, prioritized view, completion summary
-- Limits: Do NOT rescore or re-gather items
-- Dependencies: step-c-03-score.md (finalized scored initiatives with Track assignments)
-
-## MANDATORY SEQUENCE
-
-**CRITICAL:** Follow this sequence exactly. Do not skip, reorder, or improvise.
-
-### 1. Load Format Specification
-
-Load `{templateFile}` (backlog-format-spec.md) and reference:
-- **Metadata header** format (title, Created, Method, Last Updated)
-- **Section hierarchy** — all 7 H2 sections in exact order
-- **Table formats** — Category table (10 columns), Prioritized View (6 columns), Exploration Candidates (4 columns)
-- **Item ID format** — Category prefix letter + sequential number
-- **Provenance format** — "Added from Create mode, [date]"
-
-### 2. Generate Metadata Header
-
-```markdown
-# Convoke Initiatives Backlog
-
-**Created:** [current date YYYY-MM-DD]
-**Method:** RICE (Reach, Impact, Confidence, Effort)
-**Last Updated:** [current date YYYY-MM-DD]
-```
-
-### 3. Generate RICE Scoring Guide Section
-
-Create the `## RICE Scoring Guide` section with an inline summary of the methodology:
-- Composite formula: Score = (R x I x C) / E
-- Factor scales: Reach (1-10), Impact (0.25-3), Confidence (20-100%), Effort (1-10)
-- Sort order: Descending by score, tiebreak by Confidence then insertion order
-
-### 4. Generate Backlog Section with Category Tables
-
-Create the `## Backlog` section. For each unique category in the scored items:
-
-1. Create an H3 heading: `### [Category Name]`
-2. Create a 10-column table:
-
-```markdown
-| # | Initiative | Source | R | I | C | E | Score | Track | Status |
-|---|-----------|--------|---|---|---|---|-------|-------|--------|
-```
-
-3. For each item in this category:
-   - **#:** Generate item ID using category prefix letter + sequential number within category (e.g., D1, D2, P1)
-     - Category prefix mapping: D = Documentation & Onboarding, U = Update & Migration System, T = Testing & CI, I = Infrastructure, A = Agent Quality & Consistency, P = Platform & Product Vision
-     - New categories: use the first uppercase letter of the category name that is not already in use (D, U, T, I, A, P are reserved)
-   - **Initiative:** `**[Title]** — [description]. Added from Create mode, [date]`
-   - **Source:** "Create mode"
-   - **R, I, C, E:** Individual RICE component scores (C as percentage, e.g., 70%)
-   - **Score:** Composite score, one decimal place
-   - **Track:** "Keep the lights on" or "Move the needle"
-   - **Status:** "Backlog"
-
-### 5. Generate Empty Sections
-
-Create the following sections with empty content:
-
-**Exploration Candidates:**
-```markdown
-## Exploration Candidates
-
-| # | Initiative | Source | Next Step |
-|---|-----------|--------|-----------|
-```
-
-**Epic Groupings:**
-```markdown
-## Epic Groupings
-
-*No epic groupings defined yet.*
-```
-
-**Completed:**
-```markdown
-## Completed
-
-*No completed items yet.*
-```
-
-### 6. Generate Prioritized View
-
-Create the `## Prioritized View (by RICE Score)` section:
-
-1. Collect ALL items from all category tables
-2. Sort by composite RICE score descending
-3. Tiebreak: (1) Higher Confidence first, (2) Newer insertion order first
-4. Generate sequential rank numbers starting at 1
-
-```markdown
-## Prioritized View (by RICE Score)
-
-| Rank | # | Initiative | Score | Track | Category |
-|------|---|-----------|-------|-------|----------|
-```
-
-### 7. Generate Change Log
-
-Create the `## Change Log` section with the initial creation entry:
-
-```markdown
-## Change Log
-
-| Date | Change |
-|------|--------|
-| [YYYY-MM-DD] | Create: Bootstrapped new backlog with [N] items ([list categories affected]). |
-```
-
-### 8. Write Complete File
-
-Write the complete assembled backlog to `{outputFile}`. The file must contain all 7 H2 sections in the correct order as specified by the format spec.
-
-### 9. Completion Summary & Return to Menu
-
-After successful write, display:
-
-> **Create Complete**
->
-> **Items created:** [N]
-> **Categories:** [list category names]
->
-> **Top 3 Positions:**
-> 1. [#ID] [title] — Score: [X.X]
-> 2. [#ID] [title] — Score: [X.X]
-> 3. [#ID] [title] — Score: [X.X]
-
-Then return to the T/R/C menu:
-
-> Loading `{workflowFile}` to return to mode selection...
-
-Load, read the entire file, and execute `{workflowFile}`.
-
-## 🚨 SYSTEM SUCCESS/FAILURE METRICS:
-### ✅ SUCCESS: Complete backlog file generated with all 7 H2 sections in correct order, items placed in correct category tables with 10 columns, item IDs generated correctly, provenance tags added, prioritized view sorted and generated with 6 columns, changelog entry added, completion summary displayed with top 3, T/R/C menu re-presented
-### ❌ SYSTEM FAILURE: Missing H2 sections, wrong section order, items without provenance, wrong column counts, item IDs not generated, prioritized view not sorted, no changelog entry, no completion summary, no return to menu
-**Master Rule:** Skipping steps is FORBIDDEN.