convoke-agents 2.3.1 → 3.0.0

package/_bmad/bme/_gyre/workflows/accuracy-validation/steps/step-03-score-results.md

@@ -0,0 +1,143 @@
+---
+step: 3
+workflow: accuracy-validation
+title: Score Results
+---
+
+# Step 3: Score Results
+
+Score each capability for relevance and compute accuracy per archetype.
+
+## MANDATORY EXECUTION RULES
+
+- Score EVERY capability — do not skip any
+- Apply scoring criteria consistently across archetypes
+- Be honest about borderline cases — use 0.5, not 1.0, when uncertain
+- Document reasoning for any capability scored 0.0 (irrelevant)
+- The user makes the final call on disputed scores
+
+## SCORING CRITERIA
+
+For each capability, assign a relevance score:
+
+| Score | Label | Criteria |
+|-------|-------|----------|
+| **1.0** | Relevant | Would appear in a production readiness checklist for this stack, written by a domain expert. Clear, specific, and actionable. |
+| **0.5** | Partially relevant | Related to the stack's concerns but either: (a) too generic to be actionable, (b) specific to a different deployment model, or (c) relevant but poorly described |
+| **0.0** | Irrelevant | No meaningful relationship to this stack. Wrong technology, wrong domain, or nonsensical for the architecture. |
+
+### Scoring Guidelines
+
+**Score 1.0 when:**
+- The capability references technology actually in the stack (e.g., "Kubernetes liveness probes" for a K8s-deployed service)
+- The practice is industry-standard for this stack type (e.g., "structured logging" for any production service)
+- The description explains WHY it matters for THIS stack (not a generic definition)
+
+**Score 0.5 when:**
+- The capability is correct but the description is too generic (e.g., "monitoring" without specifying what to monitor)
+- The capability applies to a related but different deployment model (e.g., "ECS task health" for a K8s service)
+- The capability is relevant but at a different maturity level than the stack suggests
+
+**Score 0.0 when:**
+- The capability references technology not in the stack at all
+- The capability is a duplicate of another capability (higher-quality version gets the score)
+- The capability is meaningless or contradictory (e.g., "serverless cold start optimization" for a bare-metal service)
+
+## SCORING PROCESS
+
+Present each archetype's capabilities for scoring:
+
+```
+## Scoring: Archetype [N] — [Name]
+
+| # | Capability | Score | Reasoning |
+|---|-----------|:-----:|-----------|
+| 1 | [name]: [description summary] | [1.0/0.5/0.0] | [brief reasoning] |
+| 2 | ... | | |
+
+**Total capabilities:** [N]
+**Sum of scores:** [X]
+**Accuracy:** [X/N = Y%]
+```
+
+After scoring all archetypes, present the summary:
+
+```
+## Accuracy Validation Results
+
+| Archetype | Capabilities | Sum | Accuracy | Pass? |
+|-----------|:-----------:|:---:|:--------:|:-----:|
+| [Archetype 1] | [N] | [X] | [Y%] | ✓/✗ |
+| [Archetype 2] | [N] | [X] | [Y%] | ✓/✗ |
+| [Archetype 3] | [N] | [X] | [Y%] | ✓/✗ |
+
+**Overall:** [PASS / FAIL] — [lowest accuracy]% (gate: ≥70%)
+```
+
+## GATE DECISION
+
+### If PASS (all archetypes ≥70%):
+
+```
+✅ Model accuracy validated. Atlas is ready for production use.
+
+**Findings:**
+- Strongest archetype: [name] at [X%]
+- Weakest archetype: [name] at [X%]
+- Common issues: [brief summary of 0.0 and 0.5 patterns]
+
+**Recommendation:** Proceed to Epic 3 (Absence Detection).
+```
+
+### If FAIL (any archetype <70%):
+
+```
+❌ Model accuracy below threshold. Iteration required.
+
+**Failing archetypes:**
+- [name]: [X%] — [primary issue pattern]
+
+**Iteration guidance:**
+1. Review 0.0-scored capabilities — are they prompt issues or knowledge gaps?
+2. Review 0.5-scored capabilities — can descriptions be improved?
+3. Adjust Atlas's generation prompts (step-02-generate-capabilities.md)
+4. Re-run this validation workflow
+
+**BLOCKER:** Do not proceed to Epic 3 until ≥70% accuracy achieved across all archetypes.
+```
+
+## OUTPUT ARTIFACT
+
+Write the validation results to `_bmad-output/gyre-artifacts/accuracy-validation-[date].md` for team reference:
+
+```markdown
+# Gyre Model Accuracy Validation — [date]
+
+## Summary
+- **Result:** [PASS/FAIL]
+- **Archetypes tested:** [N]
+- **Accuracy range:** [lowest%] — [highest%]
+- **Gate threshold:** ≥70%
+
+## Detailed Scores
+[Full scoring tables from above]
+
+## Methodology Notes
+- [Live scan vs synthetic profiles used]
+- [Web search performed vs skipped]
+- [Any scoring disputes and resolutions]
+```
+
+---
+
+## Gyre Compass
+
+Based on what you just completed, here are your options:
+
+| If you want to... | Consider next... | Agent | Why |
+|---|---|---|---|
+| Iterate model prompts | model-generation | Atlas 📐 | Improve accuracy for failing archetypes |
+| Run full analysis pipeline | full-analysis | Scout 🔎 | Complete end-to-end with validated model |
+| Re-detect a different stack | stack-detection | Scout 🔎 | Test against a new archetype |
+
+> **Note:** These are recommendations. You can run any Gyre workflow at any time.

package/_bmad/bme/_gyre/workflows/accuracy-validation/workflow.md

@@ -0,0 +1,41 @@
+---
+name: accuracy-validation
+agent: model-curator
+title: Model Accuracy Validation
+description: Pre-pilot validation of model accuracy against synthetic ground truth repos — NFR19 ≥70% gate
+steps: 3
+---
+
+# Accuracy Validation Workflow
+
+Validates that Atlas can generate capabilities manifests that are ≥70% relevant across diverse stack archetypes. This is the **go/no-go gate** for the entire Gyre product (NFR19).
+
+## Purpose
+
+Model generation is the critical path for Gyre. If Atlas produces irrelevant capabilities, Lens will flag false positives and Coach will waste the user's time reviewing noise. This workflow provides a repeatable methodology to measure and iterate model quality.
+
+## Scoring Methodology
+
+Each generated capability is scored:
+
+| Score | Meaning | Criteria |
+|-------|---------|----------|
+| 1.0 | **Relevant** | Capability is appropriate for this stack archetype and would appear in a production readiness checklist written by an expert |
+| 0.5 | **Partially relevant** | Capability is tangentially related but not specific to this stack, OR is relevant but poorly described |
+| 0.0 | **Irrelevant** | Capability has no meaningful relationship to this stack archetype |
+
+**Accuracy formula:** `accuracy = sum_of_scores / total_capabilities`
+
+## Gate Criteria
+
+- Run against ≥3 stack archetypes (different language/framework/deployment combos)
+- ≥70% accuracy across ALL archetypes (not averaged)
+- If any archetype scores <70%, iterate Atlas prompts before proceeding to Epic 3
+
+## Instructions
+
+Load the first step to begin:
+
+```
+Load step: {project-root}/_bmad/bme/_gyre/workflows/accuracy-validation/steps/step-01-select-repos.md
+```

package/_bmad/bme/_gyre/workflows/delta-report/steps/step-01-load-history.md

@@ -0,0 +1,63 @@
+---
+step: 1
+workflow: delta-report
+title: Load History
+implements: Story 4.6 (FR39)
+---
+
+# Step 1: Load History
+
+Load current findings and previous findings for comparison.
+
+## MANDATORY EXECUTION RULES
+
+- Current findings (`.gyre/findings.yaml`) MUST exist — if missing, STOP
+- Previous findings (`.gyre/history.yaml`) are optional — first run has no history
+
+## EXECUTION
+
+### 1. Load Current Findings
+
+Read `.gyre/findings.yaml`. If missing:
+
+```
+❌ No current findings found at .gyre/findings.yaml
+
+Delta report requires a current analysis to compare against.
+Run gap-analysis first to generate findings, then run delta-report.
+```
+
+Then STOP — do not proceed.
+
+Parse the findings array and compound_findings array from GC3.
+
+### 2. Load Previous Findings
+
+Read `.gyre/history.yaml`. If missing:
+
+```
+💡 No previous findings found — this is your first delta-capable run.
+
+All current findings will be tagged [NEW]. After this report,
+your current findings will be saved as history for future comparison.
+```
+
+Set `first_run = true` and proceed with empty previous findings.
+
+If present, parse the findings array and compound_findings array.
+
+### 3. Validate Compatibility
+
+Check that both files have the same schema version. If versions differ:
+
+```
+⚠️ Schema version mismatch: current is v[X], history is v[Y].
+
+Proceeding with best-effort comparison — some findings may not correlate perfectly.
+```
+
+---
+
+## NEXT STEP
+
+Load step: {project-root}/_bmad/bme/_gyre/workflows/delta-report/steps/step-02-compute-delta.md

package/_bmad/bme/_gyre/workflows/delta-report/steps/step-02-compute-delta.md

@@ -0,0 +1,72 @@
+---
+step: 2
+workflow: delta-report
+title: Compute Delta
+implements: Story 4.6 (FR40)
+---
+
+# Step 2: Compute Delta
+
+Compare current findings against previous findings to classify each as new, carried-forward, or resolved.
+
+## MANDATORY EXECUTION RULES
+
+- Match findings by `capability_ref` (primary key) and `domain` (secondary key)
+- New = in current but not in previous
+- Carried-forward = in both current and previous (same capability_ref)
+- Resolved = in previous but not in current
+- Also compute compound finding delta using `related_findings` arrays
+
+## EXECUTION
+
+### 1. Build Finding Maps
+
+Create lookup maps from both finding sets:
+- **Current map:** `{ capability_ref → finding }` for all current findings
+- **Previous map:** `{ capability_ref → finding }` for all previous findings
+
+### 2. Classify Findings
+
+For each current finding:
+- If `capability_ref` exists in previous map → **CARRIED** (carried-forward)
+  - Note any severity changes: "was [old severity], now [new severity]"
+  - Note any confidence changes
+- If `capability_ref` NOT in previous map → **NEW**
+
+For each previous finding:
+- If `capability_ref` NOT in current map → **RESOLVED**
+
+### 3. Classify Compound Findings
+
+For each current compound:
+- If both `related_findings` IDs have carried-forward counterparts → **CARRIED**
+- Otherwise → **NEW**
+
+For each previous compound:
+- If either `related_findings` ID is resolved → **RESOLVED**
+
+### 4. Compute Summary Statistics
+
+```
+delta_summary:
+  new_findings: [count]
+  carried_forward: [count]
+  resolved: [count]
+  severity_changes: [count]
+  new_compounds: [count]
+  resolved_compounds: [count]
+  net_change: [current total - previous total] (positive = more findings)
+```
+
+### 5. First Run Handling
+
+If `first_run = true`:
+- All current findings are **NEW**
+- No carried-forward or resolved findings
+- No previous compounds
+
+---
+
+## NEXT STEP
+
+Load step: {project-root}/_bmad/bme/_gyre/workflows/delta-report/steps/step-03-present-delta.md

package/_bmad/bme/_gyre/workflows/delta-report/steps/step-03-present-delta.md

@@ -0,0 +1,143 @@
+---
+step: 3
+workflow: delta-report
+title: Present Delta
+implements: Story 4.6 (FR41)
+---
+
+# Step 3: Present Delta
+
+Present the delta report and save current findings as history for next run.
+
+## MANDATORY EXECUTION RULES
+
+- Present delta with [NEW], [CARRIED] tags (FR41)
+- List resolved findings briefly
+- Note severity changes on carried-forward findings
+- Save current findings as history after presentation
+- Output must be copy-pasteable into Slack/Jira/docs (FR49)
+
+## CONVERSATIONAL PRESENTATION
+
+### 1. Delta Header
+
+```
+## Delta Report — [Crisis Mode / Anticipation Mode]
+
+**Comparing:** [current analyzed_at] vs [previous analyzed_at]
+```
+
+If first run:
+```
+## Delta Report — First Run (Baseline)
+
+**Baseline established:** [current analyzed_at]
+All findings are new — this report establishes your baseline for future comparison.
+```
+
+### 2. Delta Summary
+
+```
+| Status | Count |
+|--------|:-----:|
+| 🆕 New findings | [N] |
+| ➡️ Carried forward | [N] |
+| ✅ Resolved | [N] |
+| **Net change** | **[+/-N]** |
+```
+
+### 3. New Findings [NEW]
+
+```
+### 🆕 New Findings
+
+| # | [NEW] Finding | Severity | Confidence |
+|---|--------------|----------|:----------:|
+| [ID] | [description] | [severity] | [confidence] |
+```
+
+If no new findings:
+```
+### 🆕 New Findings
+
+No new findings since last analysis. ✅
+```
+
+### 4. Carried Forward [CARRIED]
+
+```
+### ➡️ Carried Forward
+
+| # | [CARRIED] Finding | Severity | Change |
+|---|-------------------|----------|--------|
+| [ID] | [description] | [severity] | [unchanged / was: old severity] |
+```
+
+If no carried-forward:
+```
+### ➡️ Carried Forward
+
+No carried-forward findings — all previous findings are resolved! 🎉
+```
+
+### 5. Resolved Findings
+
+```
+### ✅ Resolved
+
+These findings from your previous analysis were not found this time:
+
+| # | Finding | Was Severity |
+|---|---------|-------------|
+| [ID] | [description] | [severity] |
+```
+
+If no resolved:
+```
+### ✅ Resolved
+
+No findings were resolved since last analysis.
+```
+
+### 6. Compound Finding Changes
+
+If there are new or resolved compounds:
+```
+### ⚡ Compound Finding Changes
+
+**New compounds:**
+- [COMPOUND-NNN]: [description] (combines [ID] + [ID])
+
+**Resolved compounds:**
+- [COMPOUND-NNN]: [description] — no longer applies
+```
+
+### 7. Save History
+
+After presenting, save current findings as history:
+
+1. Copy `.gyre/findings.yaml` content to `.gyre/history.yaml`
+2. Confirm:
+
+```
+---
+
+Current findings saved as history for next delta comparison.
+Written to `.gyre/history.yaml`
+```
+
+### 8. Gyre Compass
+
+```
+## What's Next?
+
+| If you want to... | Consider next... | Agent | Why |
+|---|---|---|---|
+| Review and customize findings | model-review | Coach 🏋️ | Walk through findings, amend capabilities |
+| Re-run analysis to check progress | gap-analysis | Lens 🔬 | See if fixes resolved findings |
+| Regenerate the model | model-generation | Atlas 📐 | Model may need adjustment |
+| Run the full pipeline | full-analysis | Scout 🔎 | Complete end-to-end analysis |
+| Share progress with your team | — | — | Commit .gyre/ directory to your repository |
+
+> **Note:** These are recommendations. You can run any Gyre workflow at any time.
+```

package/_bmad/bme/_gyre/workflows/delta-report/workflow.md

@@ -0,0 +1,34 @@
+---
+name: delta-report
+agent: readiness-analyst
+title: Delta Report
+description: Compare current findings against previous run — track progress over time
+steps: 3
+implements: Epic 4 (Story 4.6)
+---
+
+# Delta Report Workflow
+
+Compares current `.gyre/findings.yaml` against `.gyre/history.yaml` to show what changed: new findings, carried-forward findings, and resolved gaps.
+
+## Prerequisites
+
+- GC3 (Findings Report) at `.gyre/findings.yaml` — current analysis results
+- `.gyre/history.yaml` — previous findings (saved automatically after each delta report)
+
+## Pipeline
+
+| Step | File | Action |
+|------|------|--------|
+| 1 | step-01-load-history.md | Load current and previous findings |
+| 2 | step-02-compute-delta.md | Compute: new findings, carried-forward, resolved |
+| 3 | step-03-present-delta.md | Present delta with [NEW], [CARRIED], resolved list |
+
+## First Run Behavior
+
+If no `.gyre/history.yaml` exists, this is the first delta-capable run. All current findings are tagged [NEW], and the current findings are saved as history for future comparison.
+
+## Error Recovery
+
+- If `.gyre/findings.yaml` missing: inform user to run gap-analysis first
+- If `.gyre/history.yaml` missing: treat as first run — all findings are [NEW]

package/_bmad/bme/_gyre/workflows/full-analysis/steps/step-01-initialize.md

@@ -0,0 +1,68 @@
+---
+step: 1
+workflow: full-analysis
+title: Initialize Analysis
+---
+
+# Step 1: Initialize Analysis
+
+Set up the `.gyre/` directory and detect the analysis mode.
+
+## MANDATORY EXECUTION RULES
+
+- Use Claude Code tools (Glob, Read) — do NOT ask the user for filesystem information
+- Create `.gyre/` at the project root (or service root in monorepo) if it doesn't exist
+- Detect mode automatically — only ask the user if regeneration intent is ambiguous
+
+## INITIALIZATION SEQUENCE
+
+### 1. Check for Existing `.gyre/` Directory
+
+**Glob** for `.gyre/` at the project root:
+- `.gyre/stack-profile.yaml` → GC1 exists (previous detection)
+- `.gyre/capabilities.yaml` → GC2 exists (previous model generation)
+- `.gyre/findings.yaml` → GC3 exists (previous analysis)
+- `.gyre/.lock` → Concurrent analysis guard (NFR13)
+
+### 2. Detect Analysis Mode
+
+Based on what exists in `.gyre/`:
+
+| Condition | Mode | Behavior |
+|-----------|------|----------|
+| `.gyre/` does not exist | **Crisis** | First run — create directory, run full pipeline |
+| `.gyre/capabilities.yaml` exists | **Anticipation** | Re-run — skip model generation (step 3), use cached model |
+| User explicitly says "regenerate" or "fresh" | **Regeneration** | Fresh model — ignore cache, run full pipeline |
+
+### 3. Lock File Check (NFR13)
+
+If `.gyre/.lock` exists:
+- Read the lock file for timestamp and process info
+- If older than 5 minutes: warn the user, suggest removing it
+- If recent: inform the user another analysis may be in progress, ask to proceed or wait
+
+### 4. Create `.gyre/` Directory
+
+If `.gyre/` doesn't exist, create it.
+
+### 5. Report Initialization
+
+Present the initialization status conversationally:
+
+```
+## Analysis Initialized
+
+**Mode:** [Crisis / Anticipation / Regeneration]
+**Directory:** .gyre/ [created / already exists]
+**Existing artifacts:** [list any found, or "none — first run"]
+
+Starting stack detection...
+```
+
+---
+
+## NEXT STEP
+
+Proceed to stack detection:
+
+Load step: {project-root}/_bmad/bme/_gyre/workflows/full-analysis/steps/step-02-detect-stack.md

package/_bmad/bme/_gyre/workflows/full-analysis/steps/step-02-detect-stack.md

@@ -0,0 +1,49 @@
+---
+step: 2
+workflow: full-analysis
+title: Detect Stack
+---
+
+# Step 2: Detect Stack
+
+Run the stack-detection workflow inline. This step delegates to the stack-detection workflow steps for the actual scanning, classification, and guard questions.
+
+## MANDATORY EXECUTION RULES
+
+- Execute the stack-detection workflow steps sequentially (scan → classify → guard questions)
+- Write GC1 (Stack Profile) to `.gyre/stack-profile.yaml` on completion
+- If GC1 already exists and mode is **Anticipation**, ask the user: "Your stack was detected previously. Re-detect or keep existing? (re-detect / keep)"
+
+## EXECUTION
+
+### If Crisis or Regeneration Mode
+
+Execute the stack-detection workflow steps in sequence:
+
+1. Load and execute: `{project-root}/_bmad/bme/_gyre/workflows/stack-detection/steps/step-01-scan-filesystem.md`
+2. Load and execute: `{project-root}/_bmad/bme/_gyre/workflows/stack-detection/steps/step-02-classify-stack.md`
+3. Load and execute: `{project-root}/_bmad/bme/_gyre/workflows/stack-detection/steps/step-03-guard-questions.md`
+
+After user confirms the classification, write GC1 to `.gyre/stack-profile.yaml`.
+
+### If Anticipation Mode (GC1 exists)
+
+Present the existing stack profile summary and ask:
+
+```
+Your stack was previously detected as: [archetype summary from GC1]
+
+Would you like to:
+a) Keep this detection and continue to model generation
+b) Re-detect (your project may have changed)
+```
+
+If user chooses (b), run the detection steps above.
+
+---
+
+## NEXT STEP
+
+With GC1 written, proceed to model generation:
+
+Load step: {project-root}/_bmad/bme/_gyre/workflows/full-analysis/steps/step-03-generate-model.md

package/_bmad/bme/_gyre/workflows/full-analysis/steps/step-03-generate-model.md

@@ -0,0 +1,52 @@
+---
+step: 3
+workflow: full-analysis
+title: Generate Model
+---
+
+# Step 3: Generate Model
+
+Run the model-generation workflow inline. Atlas generates a capabilities manifest contextual to the detected stack.
+
+## MANDATORY EXECUTION RULES
+
+- GC1 (Stack Profile) must have been written in step 2 — if missing, STOP
+- If cached model exists and mode is **Anticipation**, load cached and skip generation
+- If mode is **Regeneration** or **Crisis**, run full model generation
+- Execute the model-generation workflow steps sequentially
+
+## EXECUTION
+
+### If Anticipation Mode (capabilities.yaml exists)
+
+Present the existing model summary:
+
+```
+Your capabilities model was previously generated: [N] capabilities for [stack summary].
+
+Would you like to:
+a) Keep this model and continue to gap analysis
+b) Regenerate (fresh model even with existing amendments)
+```
+
+If user chooses (a), skip to next step.
+If user chooses (b), proceed with generation below.
+
+### If Crisis or Regeneration Mode
+
+Execute the model-generation workflow steps in sequence:
+
+1. Load and execute: `{project-root}/_bmad/bme/_gyre/workflows/model-generation/steps/step-01-load-profile.md`
+2. Load and execute: `{project-root}/_bmad/bme/_gyre/workflows/model-generation/steps/step-02-generate-capabilities.md`
+3. Load and execute: `{project-root}/_bmad/bme/_gyre/workflows/model-generation/steps/step-03-web-enrichment.md`
+4. Load and execute: `{project-root}/_bmad/bme/_gyre/workflows/model-generation/steps/step-04-write-manifest.md`
+
+After completion, GC2 is written to `.gyre/capabilities.yaml`.
+
+---
+
+## NEXT STEP
+
+With GC2 written, proceed to gap analysis:
+
+Load step: {project-root}/_bmad/bme/_gyre/workflows/full-analysis/steps/step-04-analyze-gaps.md