convoke-agents 2.4.0 → 3.0.1

package/_bmad/bme/_gyre/workflows/stack-detection/steps/step-02-classify-stack.md

@@ -0,0 +1,111 @@
+---
+step: 2
+workflow: stack-detection
+title: Classify Stack
+---
+
+# Step 2: Classify Stack
+
+Organize scan results into a structured stack classification. Identify ambiguities that require guard questions.
+
+## MANDATORY EXECUTION RULES
+
+- Classification is derived from Step 1 evidence — do NOT introduce new scans here
+- If multiple stacks detected (monorepo), select primary and surface secondary as warning (FR1b)
+- Identify ambiguities honestly — do not force classification where evidence is unclear
+- Confidence levels must reflect actual evidence strength
+
+## CLASSIFICATION PROCESS
+
+### 1. Primary Stack Identification
+
+From the scan results, determine the **primary stack archetype**. Common archetypes:
+
+| Archetype | Indicators |
+|-----------|------------|
+| Node.js Web Service | package.json + Express/Fastify/Nest + REST endpoints |
+| Node.js Frontend App | package.json + React/Vue/Angular/Next.js/Svelte |
+| Go Microservice | go.mod + Gin/Echo/Chi + gRPC/REST + container |
+| Python Data Pipeline | requirements.txt/pyproject.toml + pandas/spark/airflow |
+| Python Web Service | requirements.txt + Django/Flask/FastAPI |
+| JVM Enterprise | pom.xml/build.gradle + Spring Boot + container orchestration |
+| Rust System Service | Cargo.toml + Actix/Axum/Tokio |
+| Ruby Web App | Gemfile + Rails/Sinatra |
+| .NET Service | *.csproj + ASP.NET + Azure indicators |
+| Multi-language | Multiple primary manifests at different paths |
+
+If the project doesn't fit a known archetype, classify it descriptively rather than forcing a fit.
+
+### 2. Multi-Stack Detection (FR1b)
+
+If multiple package manifests with deployment configs are found at different paths:
+
+- This is a **monorepo or multi-service project**
+- List each detected service root with its stack
+- **Do NOT attempt implicit boundary detection** from directory naming
+- Flag for user selection in Step 3 (or Story 1.5 monorepo handling)
+
+### 3. Confidence Assessment
+
+For each classification category, assign a confidence level:
+
+| Level | Meaning | Criteria |
+|-------|---------|----------|
+| **high** | Strong evidence from multiple sources | ≥2 confirming indicators, no contradictions |
+| **medium** | Evidence exists but could be interpreted differently | 1 strong indicator or multiple weak ones |
+| **low** | Inferred from indirect evidence | No direct indicator, classification based on related patterns |
+| **none** | No evidence found | Category left blank in profile |
+
+### 4. Ambiguity Identification
+
+Flag categories where guard questions would help:
+
+- **Deployment model ambiguous:** Dockerfile exists but no orchestration detected — could be container-based, serverless-backed, or local-dev-only
+- **Communication protocol ambiguous:** Both REST routes and gRPC protos detected — which is primary?
+- **Cloud provider ambiguous:** Multiple provider SDKs imported, or IaC references multiple providers
+- **Architecture intent unclear:** Evidence points multiple directions (e.g., monolith with microservice-style configs)
+
+Record each ambiguity with: what was detected, why it's ambiguous, and what a guard question would clarify.
+
+## CLASSIFICATION OUTPUT
+
+Present the classification to the user:
+
+```
+## Stack Classification
+
+**Primary Archetype:** [e.g., Node.js Web Service on AWS with Kubernetes]
+
+| Category | Classification | Confidence |
+|----------|---------------|:----------:|
+| Language/Framework | [value] | high/medium/low |
+| Container | [value] | high/medium/low |
+| Orchestration | [value or "not detected"] | high/medium/low/none |
+| CI/CD | [value] | high/medium/low |
+| Observability | [value or "not detected"] | high/medium/low/none |
+| Cloud Provider | [value] | high/medium/low |
+| Communication | [value] | high/medium/low |
+
+**Ambiguities found:** [count]
+[List each ambiguity briefly]
+```
+
+If secondary stacks were detected, include:
+
+```
+⚠️ **Secondary stacks detected:**
+- [path]: [stack description]
+- [path]: [stack description]
+
+Scout will analyze the primary stack. To analyze a secondary stack, select it explicitly.
+```
+
+---
+
+## NEXT STEP
+
+If ambiguities were identified → proceed to guard questions:
+
+Load step: {project-root}/_bmad/bme/_gyre/workflows/stack-detection/steps/step-03-guard-questions.md
+
+If classification is fully unambiguous (all categories high confidence, no contradictions) → skip guard questions and inform the user that detection is complete with high confidence. Proceed to GC1 contract writing (Story 1.4).

package/_bmad/bme/_gyre/workflows/stack-detection/steps/step-03-guard-questions.md

@@ -0,0 +1,117 @@
+---
+step: 3
+workflow: stack-detection
+title: Guard Questions
+---
+
+# Step 3: Guard Questions
+
+Ask targeted questions to resolve ambiguities identified in Step 2. Guard questions confirm architecture intent — they don't repeat what detection already proved.
+
+## MANDATORY EXECUTION RULES
+
+- **Maximum 3 questions.** If more than 3 ambiguities exist, prioritize by impact on downstream model generation.
+- **Skip entirely** if Step 2 classification has no ambiguities (all high confidence).
+- Questions are **derived from detection**, not a fixed checklist. Every question must reference what was found and why it's ambiguous.
+- User answers conversationally (FR7) — accept natural language, not just option numbers.
+- If user corrects a previous answer, re-classify without re-scanning (FR8).
+- Guard response processing takes <1 second (NFR3) — no additional file scanning on correction.
+- Guard options must cover ≥95% of common architectures (NFR20).
+
+## QUESTION GENERATION
+
+For each ambiguity from Step 2, generate a question following this pattern:
+
+```
+I found [evidence] which suggests [interpretation A], but [conflicting evidence or absence]
+could also mean [interpretation B].
+
+**Question:** [Specific question that resolves the ambiguity]
+
+Options:
+a) [Interpretation A] — [what this means for the analysis]
+b) [Interpretation B] — [what this means for the analysis]
+c) Something else — [tell me more]
+```
+
+### Common Guard Question Templates
+
+**Deployment model (when Dockerfile exists but no orchestration):**
+> I found a Dockerfile but no orchestration config (no k8s manifests, no ECS task definitions, no docker-compose for production).
+>
+> Is this container used for:
+> a) Production deployment (container-based, orchestrated elsewhere)
+> b) Local development only (production uses a different deployment model)
+> c) Serverless with container image (e.g., AWS Lambda container, Cloud Run)
+
+**Communication protocol (when multiple detected):**
+> I found both REST endpoints (Express routes) and gRPC definitions (.proto files).
+>
+> What's the primary communication pattern:
+> a) REST is the public API, gRPC is internal service-to-service
+> b) gRPC is primary, REST is a gateway/proxy layer
+> c) Both are primary — different clients use different protocols
+
+**Cloud provider (when ambiguous):**
+> I found Terraform files referencing both AWS and GCP providers.
+>
+> Is this:
+> a) Primarily AWS with some GCP services
+> b) Primarily GCP with some AWS services
+> c) True multi-cloud deployment
+
+## CONVERSATION FLOW
+
+1. Present all guard questions at once (up to 3), numbered clearly
+2. Accept answers in any order, any format (number, letter, natural language)
+3. After each answer, acknowledge and update the classification
+4. If user says something like "actually, I said X but it's really Y" — re-classify that category without re-scanning
+5. When all questions are answered (or user says "that's correct" / "looks good"):
+
+Present the **final classification** incorporating guard answers:
+
+```
+## Final Stack Classification
+
+**Archetype:** [updated archetype with guard refinements]
+
+| Category | Classification | Confidence | Source |
+|----------|---------------|:----------:|--------|
+| Language/Framework | [value] | high | detection |
+| Container | [value] | high | detection |
+| Orchestration | [value] | high | detection + guard |
+| CI/CD | [value] | high | detection |
+| Observability | [value] | medium | detection |
+| Cloud Provider | [value] | high | guard |
+| Communication | [value] | high | guard |
+
+Does this look correct? If so, I'll write the Stack Profile for Atlas to use.
+```
+
+## CORRECTION HANDLING (FR8)
+
+If the user corrects a previously answered guard question or any detection result:
+
+1. Accept the correction conversationally
+2. Update the affected classification category
+3. Check if the correction affects other categories (e.g., changing cloud provider might affect deployment model)
+4. Re-present the updated classification
+5. Do NOT re-scan the filesystem — classification update only
+
+## COMPLETION
+
+When the user confirms the classification is correct, the stack detection workflow is complete.
+
+The confirmed classification is ready for GC1 contract writing (Story 1.4). Scout will write the Stack Profile to `.gyre/stack-profile.yaml`.
+
+Present the compass routing options:
+
+```
+**What's next?**
+
+| Option | Description |
+|--------|-------------|
+| Write Stack Profile | Save classification as GC1 artifact for Atlas |
+| Chat | Discuss the detection results with Scout |
+| Menu | Return to Scout's main menu |
+```

package/_bmad/bme/_gyre/workflows/stack-detection/workflow.md

@@ -0,0 +1,42 @@
+---
+workflow: stack-detection
+type: step-file
+description: Detect and classify project technology stack through filesystem analysis
+author: Scout (stack-detective)
+version: 1.0.0
+---
+
+# Stack Detection Workflow
+
+This workflow guides Scout through scanning a project's filesystem to detect and classify its technology stack. The output is a Stack Profile that downstream agents use for contextual model generation.
+
+## What is Stack Detection?
+
+Stack detection identifies the technologies, frameworks, infrastructure, and tooling used in a project by examining its filesystem artifacts — package manifests, config files, IaC templates, CI pipelines, and dependency declarations. No code is executed; all detection is static.
+
+## Workflow Structure
+
+**Step-file architecture:**
+- Just-in-time loading (each step loads only when needed)
+- Sequential enforcement (must complete step N before step N+1)
+- State tracking in frontmatter (progress preserved)
+
+## Steps Overview
+
+1. **Scan Filesystem** — Use Glob, Grep, and Read to discover technology indicators
+2. **Classify Stack** — Organize findings into a structured classification with confidence levels
+3. **Guard Questions** — Ask ≤3 targeted questions to resolve ambiguities (skip if unambiguous)
+
+## Output
+
+**Artifact:** Stack Profile at `.gyre/stack-profile.yaml` (GC1 contract)
+
+**Privacy boundary:** Stack Profile contains technology categories only — NOT file contents, file paths, version numbers, dependency counts, dependency names, or secrets.
+
+---
+
+## INITIALIZATION
+
+Load config from {project-root}/_bmad/bme/_gyre/config.yaml
+
+Load step: {project-root}/_bmad/bme/_gyre/workflows/stack-detection/steps/step-01-scan-filesystem.md

package/_bmad/bme/_vortex/config.yaml

@@ -33,7 +33,7 @@ workflows:
   - learning-card
   - pivot-patch-persevere
   - vortex-navigation
-version: 2.3.1
+version: 3.0.0
 user_name: '{user}'
 communication_language: en
 party_mode_enabled: true

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "convoke-agents",
-  "version": "2.4.0",
+  "version": "3.0.1",
   "description": "Agent teams for complex systems, compatible with BMad Method",
   "main": "index.js",
   "files": [
@@ -8,6 +8,7 @@
     "scripts/",
     "_bmad/bme/_vortex/",
     "_bmad/bme/_enhance/",
+    "_bmad/bme/_gyre/",
     "INSTALLATION.md",
     "UPDATE-GUIDE.md",
     "CHANGELOG.md",
@@ -17,6 +18,7 @@
   ],
   "bin": {
     "convoke-install-vortex": "scripts/install-vortex-agents.js",
+    "convoke-install-gyre": "scripts/install-gyre-agents.js",
     "convoke-install": "scripts/install-all-agents.js",
     "convoke-update": "scripts/update/convoke-update.js",
     "convoke-version": "scripts/update/convoke-version.js",
@@ -33,7 +35,8 @@
     "test:all": "node --test tests/**/*.test.js",
     "test:coverage": "c8 node --test tests/unit/*.test.js tests/integration/*.test.js tests/p0/*.test.js",
     "lint": "eslint scripts/ index.js tests/",
-    "docs:audit": "node scripts/docs-audit.js"
+    "docs:audit": "node scripts/docs-audit.js",
+    "archive": "node scripts/archive.js"
   },
   "keywords": [
     "convoke-agents",

package/scripts/archive.js

@@ -0,0 +1,304 @@
+#!/usr/bin/env node
+
+const fs = require('fs-extra');
+const path = require('path');
+const { findProjectRoot } = require('./update/lib/utils');
+
+// --- Category registry from ADR ---
+const VALID_CATEGORIES = [
+  'prd', 'epic', 'arch', 'adr', 'brief', 'report', 'spec', 'vision',
+  'hc', 'persona', 'experiment', 'learning', 'sprint', 'decision',
+  'research'
+];
+
+const NAMING_PATTERN = /^[a-z][a-z0-9-]*\.(?:md|yaml)$/;
+
+// Living documents that are exempt from the category prefix requirement
+const EXEMPT_FILES = [
+  'architecture.md', 'architecture-gyre.md',
+  'prd.md', 'initiatives-backlog.md'
+];
+
+// Directories to scan for superseded files (relative to _bmad-output/)
+const SCAN_DIRS = ['planning-artifacts', 'vortex-artifacts', 'implementation-artifacts'];
+
+// Directories/files to skip when scanning _bmad-output/ root
+const SKIP_ROOT = ['.backups', '.logs', '_archive', ...SCAN_DIRS,
+  'brainstorming', 'design-artifacts', 'journey-examples',
+  'project-documentation', 'test-artifacts'];
+
+function isValidCategory(cat) {
+  const base = cat.replace(/\d+$/, '');
+  return VALID_CATEGORIES.includes(base) || VALID_CATEGORIES.includes(cat);
+}
+
+const DATED_PATTERN = /^(.+)-(\d{4}-\d{2}-\d{2})\.(md|yaml)$/;
+const CATEGORIZED_PATTERN = /^([a-z]+\d*)-(.+)\.(md|yaml)$/;
+
+// --- Helpers ---
+
+function parseFilename(filename) {
+  const lower = filename.toLowerCase();
+  const dated = lower.match(DATED_PATTERN);
+  const categorized = lower.match(CATEGORIZED_PATTERN);
+
+  return {
+    filename,
+    isDated: !!dated,
+    date: dated ? dated[2] : null,
+    baseName: dated ? dated[1] : lower.replace(/\.(md|yaml)$/, ''),
+    category: categorized ? categorized[1] : null,
+    hasValidCategory: categorized ? isValidCategory(categorized[1]) : false,
+    isUppercase: filename !== lower,
+    matchesConvention: NAMING_PATTERN.test(filename) && categorized && isValidCategory(categorized[1])
+  };
+}
+
+function toLowerKebab(filename) {
+  return filename.toLowerCase();
+}
+
+function groupByKey(files) {
+  const groups = {};
+  for (const f of files) {
+    if (!f.isDated) continue;
+    const key = f.baseName;
+    if (!groups[key]) groups[key] = [];
+    groups[key].push(f);
+  }
+  return groups;
+}
+
+function appendToIndex(indexPath, entries) {
+  const date = new Date().toISOString().split('T')[0];
+  let content = '';
+
+  if (!fs.existsSync(indexPath)) {
+    content = '# Archive Index\n\n_Traceability log for archived artifacts. Append-only._\n\n';
+  }
+
+  content += `\n## Automated archive — ${date}\n\n`;
+  content += '| File | Original Location | Archive Date | Reason |\n';
+  content += '|------|-------------------|--------------|--------|\n';
+
+  for (const entry of entries) {
+    content += `| ${entry.archivedAs || entry.filename} | ${entry.originalDir}/ | ${date} | ${entry.reason} |\n`;
+  }
+
+  fs.appendFileSync(indexPath, content);
+}
+
+// --- Main ---
+
+async function run() {
+  const args = process.argv.slice(2);
+  const apply = args.includes('--apply');
+  const rename = args.includes('--rename');
+  const help = args.includes('--help') || args.includes('-h');
+
+  if (help) {
+    console.log(`
+Usage: node scripts/archive.js [options]
+
+Options:
+  --apply           Execute changes (default: dry-run)
+  --rename          Include naming convention checks and fixes
+  --rename --apply  Fix uppercase filenames and archive loose root files
+  --help            Show this help
+
+Dry-run by default — shows what would happen without changing anything.
+`);
+    return;
+  }
+
+  const projectRoot = findProjectRoot();
+  if (!projectRoot) {
+    console.error('Error: Could not find project root (_bmad/ directory not found).');
+    process.exit(1);
+  }
+
+  const outputDir = path.join(projectRoot, '_bmad-output');
+  const archiveDir = path.join(outputDir, '_archive');
+  const indexPath = path.join(archiveDir, 'INDEX.md');
+
+  const actions = { archive: [], rename: [], warnings: [] };
+
+  // 1. Scan subdirectories for superseded dated files
+  for (const dir of SCAN_DIRS) {
+    const fullDir = path.join(outputDir, dir);
+    if (!fs.existsSync(fullDir)) continue;
+
+    const files = (await fs.readdir(fullDir))
+      .filter(f => !f.startsWith('.'))
+      .map(f => ({ ...parseFilename(f), dir }));
+
+    // Find superseded versions
+    const groups = groupByKey(files);
+    for (const [, group] of Object.entries(groups)) {
+      if (group.length <= 1) continue;
+
+      group.sort((a, b) => b.date.localeCompare(a.date));
+      const [newest, ...older] = group;
+
+      for (const old of older) {
+        actions.archive.push({
+          filename: old.filename,
+          originalDir: dir,
+          from: path.join(fullDir, old.filename),
+          to: path.join(archiveDir, 'superseded', old.filename),
+          reason: `Superseded by ${newest.filename}`
+        });
+      }
+    }
+
+    // Flag naming convention violations in subdirs
+    if (rename) {
+      for (const f of files) {
+        if (f.matchesConvention) continue;
+        if (EXEMPT_FILES.includes(f.filename)) continue;
+
+        const issues = [];
+        if (f.isUppercase) {
+          issues.push('uppercase in filename');
+          const newName = toLowerKebab(f.filename);
+          actions.rename.push({
+            filename: f.filename,
+            newName,
+            dir,
+            from: path.join(fullDir, f.filename),
+            to: path.join(fullDir, newName)
+          });
+        }
+        if (!NAMING_PATTERN.test(f.filename) && !f.isUppercase) {
+          issues.push('not lowercase kebab-case');
+        }
+        if (!f.hasValidCategory) {
+          issues.push(`no valid category prefix (has: ${f.category || 'none'})`);
+        }
+
+        if (issues.length > 0) {
+          actions.warnings.push({
+            filename: f.filename,
+            dir,
+            issues
+          });
+        }
+      }
+    }
+  }
+
+  // 2. Scan _bmad-output/ root for loose files
+  const rootFiles = (await fs.readdir(outputDir))
+    .filter(f => {
+      if (f.startsWith('.')) return false;
+      if (SKIP_ROOT.includes(f)) return false;
+      const fullPath = path.join(outputDir, f);
+      return fs.statSync(fullPath).isFile();
+    });
+
+  if (rootFiles.length > 0) {
+    for (const f of rootFiles) {
+      const archivedAs = toLowerKebab(f);
+      actions.archive.push({
+        filename: f,
+        archivedAs,
+        originalDir: '_bmad-output (root)',
+        from: path.join(outputDir, f),
+        to: path.join(archiveDir, 'exploratory', archivedAs),
+        reason: 'Loose file in _bmad-output root — archived as historical'
+      });
+    }
+  }
+
+  // --- Report ---
+
+  const mode = apply ? 'APPLY' : 'DRY-RUN';
+  console.log(`\n=== Convoke Archive (${mode}) ===\n`);
+
+  const totalActions = actions.archive.length + actions.rename.length + actions.warnings.length;
+  if (totalActions === 0) {
+    console.log('Everything looks clean. No actions needed.');
+    return;
+  }
+
+  // Loose/superseded files to archive
+  if (actions.archive.length > 0) {
+    console.log(`📦 Files to archive: ${actions.archive.length}\n`);
+    for (const a of actions.archive) {
+      const dest = path.relative(outputDir, a.to);
+      console.log(`  ${a.originalDir === '_bmad-output (root)' ? '' : a.originalDir + '/'}${a.filename}`);
+      console.log(`    → ${dest}`);
+      console.log(`    Reason: ${a.reason}\n`);
+    }
+  }
+
+  // Renames (uppercase → lowercase)
+  if (actions.rename.length > 0) {
+    console.log(`✏️  Files to rename: ${actions.rename.length}\n`);
+    for (const r of actions.rename) {
+      console.log(`  ${r.dir}/${r.filename}  →  ${r.newName}`);
+    }
+    console.log('');
+  }
+
+  // Convention warnings (non-actionable — just flagged)
+  if (actions.warnings.length > 0) {
+    console.log(`⚠️  Naming convention warnings: ${actions.warnings.length}\n`);
+    for (const w of actions.warnings) {
+      console.log(`  ${w.dir}/${w.filename}`);
+      console.log(`    Issues: ${w.issues.join(', ')}`);
+    }
+    console.log('');
+  }
+
+  // Execute if --apply
+  if (apply) {
+    let executed = 0;
+
+    // Archive moves
+    if (actions.archive.length > 0) {
+      console.log('Executing archive moves...\n');
+      const indexEntries = [];
+
+      for (const a of actions.archive) {
+        await fs.ensureDir(path.dirname(a.to));
+        await fs.move(a.from, a.to, { overwrite: false });
+        indexEntries.push(a);
+        executed++;
+        console.log(`  ✅ Archived: ${a.filename}${a.archivedAs && a.archivedAs !== a.filename ? ` → ${a.archivedAs}` : ''}`);
+      }
+
+      appendToIndex(indexPath, indexEntries);
+      console.log(`\n📋 Updated _archive/INDEX.md with ${indexEntries.length} entries.`);
+    }
+
+    // Renames
+    if (rename && actions.rename.length > 0) {
+      console.log('\nExecuting renames...\n');
+      for (const r of actions.rename) {
+        await fs.move(r.from, r.to, { overwrite: false });
+        executed++;
+        console.log(`  ✅ Renamed: ${r.filename} → ${r.newName}`);
+      }
+    }
+
+    console.log(`\nDone. ${executed} actions executed.`);
+  }
+
+  // Summary
+  console.log('\n--- Summary ---');
+  console.log(`  Files to archive: ${actions.archive.length}`);
+  if (rename) {
+    console.log(`  Files to rename: ${actions.rename.length}`);
+    console.log(`  Convention warnings: ${actions.warnings.length}`);
+  }
+  if (!apply && (actions.archive.length > 0 || actions.rename.length > 0)) {
+    console.log('\n  Run with --apply to execute changes.');
+  }
+  console.log('');
+}
+
+run().catch(err => {
+  console.error('Archive error:', err.message);
+  process.exit(1);
+});