convoke-agents 2.4.0 → 3.0.1

package/_bmad/bme/_gyre/workflows/gap-analysis/steps/step-05-present-findings.md

@@ -0,0 +1,172 @@
+---
+step: 5
+workflow: gap-analysis
+title: Present Findings
+---
+
+# Step 5: Present Findings
+
+Write findings to GC3 artifact and present a conversational severity-first summary.
+
+## MANDATORY EXECUTION RULES
+
+- Write GC3 to `.gyre/findings.yaml` before presenting to the user
+- Present severity-first: blockers, then recommended, then nice-to-have (FR33)
+- Include novelty ratio: how many findings are contextual vs what a static linter would catch (FR34)
+- Include compound findings with reasoning chains (FR35)
+- Output must be copy-pasteable into Slack/Jira/docs (FR49)
+- If analysis failed partway, report what was found and offer to retry (NFR11)
+
+## WRITE GC3 ARTIFACT
+
+Write the following to `.gyre/findings.yaml`:
+
+```yaml
+---
+contract: GC3
+type: artifact
+source_agent: lens
+source_workflow: gap-analysis
+target_agents: [coach]
+input_artifacts: [GC2]
+created: [today's date]
+---
+
+gyre_findings:
+  version: "1.0"
+  analyzed_at: "[ISO-8601 timestamp]"
+  mode: "[crisis|anticipation]"
+  stack_summary: "[from GC2]"
+  summary:
+    blockers: [count]
+    recommended: [count]
+    nice_to_have: [count]
+    total: [count]
+    novelty_ratio: "[X of Y contextual]"
+  findings:
+    [all OBS-NNN and DEP-NNN findings]
+  compound_findings:
+    [all COMPOUND-NNN findings]
+  sanity_check:
+    passed: [boolean]
+    warnings: [list]
+```
+
+## CONVERSATIONAL PRESENTATION
+
+Present findings in this order:
+
+### 1. Mode Indicator (FR37)
+
+```
+## Gap Analysis — [Crisis Mode / Anticipation Mode]
+```
+
+### 2. Severity-First Summary (FR33)
+
+```
+**[stack_summary]**
+
+| Severity | Count |
+|----------|:-----:|
+| 🔴 Blockers | [N] |
+| 🟡 Recommended | [N] |
+| 🟢 Nice-to-have | [N] |
+| **Total findings** | **[N]** |
+
+**Novelty ratio:** [X] of [Y] findings are contextual — gaps a generic linter would miss.
+```
+
+### 3. Blocker Findings (if any)
+
+```
+### 🔴 Blockers
+
+**[OBS/DEP-NNN] [capability name]**
+[description]
+- **Evidence:** [evidence_summary]
+- **Confidence:** [high/medium/low]
+- **Why blocker:** [severity_rationale]
+```
+
+### 4. Compound Findings (if any, FR35)
+
+```
+### ⚡ Compound Findings
+
+**[COMPOUND-NNN] [description headline]**
+- Combines: [OBS-NNN] + [DEP-NNN]
+- **Impact:** [combined_impact reasoning chain]
+- **Confidence:** [compound confidence]
+```
+
+### 5. Recommended Findings
+
+```
+### 🟡 Recommended
+
+| # | Finding | Capability | Confidence |
+|---|---------|-----------|:----------:|
+| [DEP-NNN] | [description] | [capability name] | [high/medium/low] |
+```
+
+### 6. Nice-to-Have Findings
+
+```
+### 🟢 Nice-to-have
+
+| # | Finding | Capability | Confidence |
+|---|---------|-----------|:----------:|
+| [OBS-NNN] | [description] | [capability name] | [high/medium/low] |
+```
+
+### 7. Sanity Check Warnings (if any)
+
+```
+### ⚠️ Analysis Notes
+
+[List any sanity_check.warnings]
+```
+
+### 8. Summary Footer
+
+```
+Written to `.gyre/findings.yaml`
+
+---
+```
+
+## ERROR RECOVERY (NFR11, FR56)
+
+If analysis failed after model generation:
+
+```
+## Analysis Partially Complete
+
+[domain] analysis encountered an error: [brief description]
+
+**What was completed:**
+- ✅ [completed domain]: [N] findings
+- ❌ [failed domain]: analysis did not complete
+
+**Your capabilities manifest (.gyre/capabilities.yaml) is safe** — it was written before analysis started.
+
+**Options:**
+a) View findings from the completed domain
+b) Retry the failed domain
+c) Exit and investigate
+```
+
+---
+
+## Gyre Compass
+
+Based on what you just completed, here are your options:
+
+| If you want to... | Consider next... | Agent | Why |
+|---|---|---|---|
+| Review findings and customize the model | model-review | Coach 🏋️ | Walk through findings, amend capabilities |
+| Compare with previous analysis | delta-report | Lens 🔬 | Track progress since last run |
+| Regenerate the model with different parameters | model-generation | Atlas 📐 | Model may need adjustment based on findings |
+
+> **Note:** These are recommendations. You can run any Gyre workflow at any time.

package/_bmad/bme/_gyre/workflows/gap-analysis/workflow.md

@@ -0,0 +1,38 @@
+---
+name: gap-analysis
+agent: readiness-analyst
+title: Gap Analysis
+description: Run absence detection across observability and deployment domains with cross-domain correlation
+steps: 5
+---
+
+# Gap Analysis Workflow
+
+Lens compares each capability in the manifest against actual filesystem evidence. Identifies what's missing — not just what's misconfigured.
+
+## Prerequisites
+
+- GC2 (Capabilities Manifest) must exist at `.gyre/capabilities.yaml`
+- If GC2 doesn't exist, direct the user to run `model-generation` with Atlas first
+
+## Pipeline
+
+| Step | File | Action |
+|------|------|--------|
+| 1 | step-01-load-manifest.md | Load GC2 (capabilities.yaml) |
+| 2 | step-02-observability-analysis.md | For each observability capability: search filesystem for evidence |
+| 3 | step-03-deployment-analysis.md | For each deployment capability: search filesystem for evidence |
+| 4 | step-04-cross-domain-correlation.md | Identify compound patterns across domains |
+| 5 | step-05-present-findings.md | Present severity-first summary, write GC3 |
+
+## Privacy Boundary
+
+Findings reference capability IDs and evidence summaries — NOT file contents or secrets. Evidence is described categorically: "health check endpoint found" not the endpoint source code.
+
+## Instructions
+
+Load the first step to begin:
+
+```
+Load step: {project-root}/_bmad/bme/_gyre/workflows/gap-analysis/steps/step-01-load-manifest.md
+```

package/_bmad/bme/_gyre/workflows/model-generation/steps/step-01-load-profile.md

@@ -0,0 +1,74 @@
+---
+step: 1
+workflow: model-generation
+title: Load Stack Profile
+---
+
+# Step 1: Load Stack Profile
+
+Load the GC1 Stack Profile and check for existing amendments from previous reviews.
+
+## MANDATORY EXECUTION RULES
+
+- Use Claude Code Read tool to load `.gyre/stack-profile.yaml`
+- If file doesn't exist, do NOT proceed — inform user to run stack-detection first
+- Check for existing GC4 amendments to respect on regeneration
+
+## EXECUTION SEQUENCE
+
+### 1. Load GC1 (Stack Profile)
+
+**Read** `.gyre/stack-profile.yaml`:
+
+- Parse the YAML content
+- Extract: primary_language, primary_framework, container_orchestration, ci_cd_platform, observability_tooling, cloud_provider, communication_protocol
+- Extract guard_answers if present
+- Note detection_confidence level
+
+**If file not found:**
+```
+I need a Stack Profile (GC1) before I can generate a capabilities model.
+
+Please run Scout's stack detection first:
+- Activate Scout: /bmad-agent-bme-stack-detective
+- Select [DS] Detect Stack
+
+Or run the full analysis pipeline which includes detection:
+- Select [FA] Full Analysis
+```
+Then STOP — do not proceed.
+
+### 2. Check for Existing Amendments (GC4)
+
+**Read** `.gyre/capabilities.yaml` (if it exists):
+
+- If the file exists, this is a **regeneration** — previous model exists
+- Look for capabilities with `amended: true` — these are user-modified
+- Look for capabilities with `removed: true` — these were explicitly removed
+- Store amendments list for step 2 (generate will respect them)
+
+**If capabilities.yaml doesn't exist:** This is a first-time generation — no amendments to respect.
+
+### 3. Present Profile Summary
+
+```
+## Stack Profile Loaded
+
+**Stack:** [primary_language] / [primary_framework]
+**Deployment:** [container_orchestration] on [cloud_provider]
+**CI/CD:** [ci_cd_platform]
+**Observability:** [observability_tooling list]
+**Communication:** [communication_protocol]
+**Confidence:** [detection_confidence]
+
+[If regeneration]: **Previous model found** — [N] capabilities, [M] amendments will be preserved.
+[If first-time]: **First generation** — no previous model.
+
+Generating capabilities for your stack...
+```
+
+---
+
+## NEXT STEP
+
+Load step: {project-root}/_bmad/bme/_gyre/workflows/model-generation/steps/step-02-generate-capabilities.md

package/_bmad/bme/_gyre/workflows/model-generation/steps/step-02-generate-capabilities.md

@@ -0,0 +1,116 @@
+---
+step: 2
+workflow: model-generation
+title: Generate Capabilities
+---
+
+# Step 2: Generate Capabilities
+
+Generate capabilities relevant to the detected stack using industry standards and stack-specific reasoning.
+
+## MANDATORY EXECUTION RULES
+
+- Every capability MUST be relevant to THIS stack — do not generate generic checklists
+- Each capability must explain WHY it matters for this specific stack/deployment/cloud combination
+- Generate ≥20 capabilities for supported archetypes; fewer triggers limited_coverage warning
+- Respect GC4 amendments: removed capabilities stay removed, amended capabilities persist unchanged
+- Source every capability: "standard" (industry framework), "practice" (common pattern), or "reasoning" (derived from stack analysis)
+
+## CAPABILITY SCHEMA
+
+Each capability must have:
+
+```yaml
+- id: string              # kebab-case, e.g., "health-check-liveness"
+  category: string        # "observability" | "deployment" | "reliability" | "security"
+  name: string            # human-readable, e.g., "Liveness Health Check"
+  description: string     # 1-3 sentences: what it is + why it matters for THIS stack
+  source: string          # "standard" | "practice" | "reasoning"
+  relevance: string       # why this matters for THIS stack specifically
+  amended: false          # set by Coach during review
+  removed: false          # set by Coach during review
+```
+
+## GENERATION APPROACH
+
+### Domain Coverage
+
+Generate capabilities across these domains, weighted by stack relevance:
+
+**Observability** (typically 6-10 capabilities):
+- Structured logging (format, correlation IDs, log levels)
+- Distributed tracing (instrumentation, propagation, sampling)
+- Metrics collection (application, runtime, business)
+- Health checks (liveness, readiness, startup probes)
+- Alerting and dashboards
+- Error tracking and reporting
+
+**Deployment** (typically 5-8 capabilities):
+- Container configuration (multi-stage builds, security, resource limits)
+- CI/CD pipeline (build, test, deploy stages)
+- Rollback strategy
+- Environment configuration management
+- Infrastructure as code
+- Deployment strategy (blue-green, canary, rolling)
+
+**Reliability** (typically 4-6 capabilities):
+- Graceful shutdown and connection draining
+- Circuit breakers and retry policies
+- Rate limiting
+- Dependency health monitoring
+- Chaos engineering / fault injection readiness
+
+**Security** (typically 3-5 capabilities):
+- Secrets management (not hardcoded)
+- Dependency vulnerability scanning
+- Network policies / service mesh
+- Authentication and authorization patterns
+- Container image scanning
+
+### Stack-Specific Adjustments
+
+Adjust capabilities based on the Stack Profile:
+
+| Stack Signal | Adjustment |
+|-------------|------------|
+| **Kubernetes** | Add: liveness/readiness/startup probes, pod disruption budgets, resource requests/limits, network policies |
+| **Serverless** | Add: cold start optimization, function timeout config, concurrency limits. Remove: container-specific items |
+| **gRPC** | Add: gRPC health checking protocol, reflection API, deadline propagation. Adjust: HTTP health → gRPC health |
+| **Docker Compose only** | Reduce orchestration capabilities. Focus: service dependencies, volume persistence, compose health checks |
+| **GitHub Actions** | Add: workflow caching, matrix builds, environment protection rules |
+| **OpenTelemetry detected** | Adjust: tracing capabilities reference OTel SDK. Add: collector configuration, OTLP export |
+| **No observability detected** | Weight observability capabilities higher — these are likely the biggest gaps |
+| **AWS** | Add: CloudWatch integration, IAM roles, Security Groups. Adjust: IaC references to Terraform/CDK/CloudFormation |
+| **GCP** | Add: Cloud Logging, Cloud Monitoring, Workload Identity. Adjust: IaC references |
+
+### Amendment Handling (GC4 Regeneration)
+
+If previous amendments exist:
+
+1. **Removed capabilities** (`removed: true`): Do NOT regenerate these — the user explicitly removed them
+2. **Amended capabilities** (`amended: true`): Keep the user's version unchanged — do not overwrite with regenerated version
+3. **New capabilities**: Add alongside preserved amendments
+4. **Unchanged capabilities**: Regenerate fresh (may pick up updated descriptions or new web search results)
+
+## OUTPUT
+
+Store the generated capabilities list in working memory for the next step (web enrichment).
+
+Present a brief progress update:
+
+```
+Generated [N] capabilities for your [language]/[framework] stack:
+- Observability: [n] capabilities
+- Deployment: [n] capabilities
+- Reliability: [n] capabilities
+- Security: [n] capabilities
+[If amendments preserved]: Preserved [M] user amendments from previous review.
+
+Enriching with current best practices...
+```
+
+---
+
+## NEXT STEP
+
+Load step: {project-root}/_bmad/bme/_gyre/workflows/model-generation/steps/step-03-web-enrichment.md

package/_bmad/bme/_gyre/workflows/model-generation/steps/step-03-web-enrichment.md

@@ -0,0 +1,89 @@
+---
+step: 3
+workflow: model-generation
+title: Web Enrichment
+---
+
+# Step 3: Web Enrichment
+
+Use web search to enrich capabilities with current best practices and validate relevance.
+
+## MANDATORY EXECUTION RULES
+
+- Web search is OPTIONAL — if WebSearch tool is unavailable, skip this step gracefully
+- Search for current-year best practices for the detected stack (FR11, NFR21)
+- When conflicting advice is found, select the most authoritative source and note the conflict
+- Mark web-enriched capabilities with source indication
+- Do NOT replace user-amended capabilities with web search results
+
+## WEB SEARCH STRATEGY
+
+### Search Queries
+
+Construct targeted queries based on the Stack Profile:
+
+1. **Stack-specific production readiness:**
+   `"[framework] production readiness checklist [current year]"`
+
+2. **Observability best practices:**
+   `"[framework] [observability tool] best practices [current year]"`
+
+3. **Deployment patterns:**
+   `"[container orchestration] deployment best practices [cloud provider]"`
+
+4. **Reliability patterns:**
+   `"[framework] reliability patterns production"`
+
+### Search Execution
+
+For each query:
+1. Execute WebSearch
+2. Scan results for capabilities not already in the generated list
+3. For existing capabilities, check if web results suggest better descriptions or updated practices
+4. For new capabilities found, add them with `source: "practice"` and note web origin
+
+### Conflict Resolution
+
+When web sources disagree:
+- Prefer official documentation (e.g., Kubernetes docs, cloud provider docs) over blog posts
+- Prefer recent sources (current year) over older ones
+- When genuinely split, note both perspectives in the capability description
+- Never silently pick one side — transparency builds trust
+
+## IF WEB SEARCH UNAVAILABLE
+
+```
+Web search is not available in this session. Proceeding with capabilities
+generated from industry standards and stack analysis.
+
+Note: You can re-run model generation later with web search enabled for
+enriched results. The model is valid without web enrichment.
+```
+
+Set `web_search_performed: false` in provenance metadata and continue to step 4.
+
+## OUTPUT
+
+Update the capabilities list with web enrichment results.
+
+Present a brief summary:
+
+```
+[If web search performed]:
+Web enrichment complete:
+- Searched [N] queries for current [year] practices
+- Updated [M] capability descriptions with current guidance
+- Added [K] new capabilities from web research
+- Sources: [list key sources referenced]
+
+[If no web search]:
+Skipped web enrichment — capabilities based on standards and stack analysis.
+
+Writing capabilities manifest...
+```
+
+---
+
+## NEXT STEP
+
+Load step: {project-root}/_bmad/bme/_gyre/workflows/model-generation/steps/step-04-write-manifest.md

package/_bmad/bme/_gyre/workflows/model-generation/steps/step-04-write-manifest.md

@@ -0,0 +1,122 @@
+---
+step: 4
+workflow: model-generation
+title: Write Manifest
+---
+
+# Step 4: Write Capabilities Manifest
+
+Write the complete capabilities manifest to `.gyre/capabilities.yaml` (GC2 contract).
+
+## MANDATORY EXECUTION RULES
+
+- Write to `.gyre/capabilities.yaml` using the GC2 schema
+- Include GC2 contract frontmatter
+- If <20 capabilities, set limited_coverage=true and warn the user (FR15)
+- If limited_coverage, offer: continue (with emphasis on review-and-amend) or abort (FR52)
+- Present model summary after writing (FR31)
+- The manifest IS the cache — subsequent runs load it, no regeneration unless explicit (NFR10)
+
+## GC2 ARTIFACT STRUCTURE
+
+Write the following YAML to `.gyre/capabilities.yaml`:
+
+```yaml
+---
+contract: GC2
+type: artifact
+source_agent: atlas
+source_workflow: model-generation
+target_agents: [lens, coach]
+input_artifacts: [GC1]
+created: [today's date]
+---
+
+gyre_manifest:
+  version: "1.0"
+  generated_at: "[ISO-8601 timestamp]"
+  stack_summary: "[one-line stack description from GC1]"
+  capability_count: [N]
+  limited_coverage: [true/false]
+  capabilities:
+    - id: "[capability-id]"
+      category: "[domain]"
+      name: "[human-readable name]"
+      description: "[1-3 sentences]"
+      source: "[standard|practice|reasoning]"
+      relevance: "[why it matters for THIS stack]"
+      amended: false
+      removed: false
+    # ... all capabilities
+  provenance:
+    standards_referenced: ["DORA", "OpenTelemetry", "Google PRR"]
+    web_search_performed: [true/false]
+    web_search_date: "[ISO-8601 or null]"
+```
+
+## WRITING PROCESS
+
+1. Construct the complete YAML document
+2. Write to `.gyre/capabilities.yaml` (overwrite if regenerating)
+3. Verify the file was written successfully by reading it back
+
+## LIMITED COVERAGE HANDLING (FR15, FR52)
+
+If capability_count < 20:
+
+```
+⚠️ **Limited Coverage Warning**
+
+Atlas generated [N] capabilities for your stack (threshold: 20).
+
+This may happen when:
+- The stack archetype is unusual or emerging
+- Key detection signals were missing
+- The combination of technologies has limited standard guidance
+
+**Options:**
+a) **Continue** — proceed to gap analysis with the current model. You can add
+   capabilities during Coach's review step.
+b) **Abort** — stop here and investigate. Consider:
+   - Re-running stack detection with more context
+   - Providing guard question answers that clarify the architecture
+
+Which would you like to do?
+```
+
+## MODEL SUMMARY (FR31)
+
+After successful write, present:
+
+```
+## Model Generated ✓
+
+**Generated [N] capabilities for your [language]/[framework] stack**
+
+| Domain | Count | Key Capabilities |
+|--------|:-----:|-----------------|
+| Observability | [n] | [top 2-3 by name] |
+| Deployment | [n] | [top 2-3 by name] |
+| Reliability | [n] | [top 2-3 by name] |
+| Security | [n] | [top 2-3 by name] |
+
+**Sources:** [standards referenced]
+**Web enriched:** [yes/no]
+[If regeneration]: **Amendments preserved:** [M] from previous review
+
+Written to `.gyre/capabilities.yaml`
+```
+
+---
+
+## Gyre Compass
+
+Based on what you just completed, here are your options:
+
+| If you want to... | Consider next... | Agent | Why |
+|---|---|---|---|
+| Analyze your stack for gaps | gap-analysis | Lens 🔬 | Capabilities Manifest (GC2) is ready for analysis |
+| Review and customize the model | model-review | Coach 🏋️ | Customize before analysis |
+| Validate model accuracy | accuracy-validation | Atlas 📐 | Pre-pilot quality gate |
+
+> **Note:** These are recommendations. You can run any Gyre workflow at any time.

package/_bmad/bme/_gyre/workflows/model-generation/workflow.md

@@ -0,0 +1,40 @@
+---
+name: model-generation
+agent: model-curator
+title: Capabilities Model Generation
+description: Generate a contextual capabilities manifest from the Stack Profile using industry standards and web search
+steps: 4
+---
+
+# Model Generation Workflow
+
+Atlas generates a capabilities manifest unique to the detected stack. Each capability includes why it matters for THIS specific stack, not generic descriptions.
+
+## Prerequisites
+
+- GC1 (Stack Profile) must exist at `.gyre/stack-profile.yaml`
+- If GC1 doesn't exist, direct the user to run `stack-detection` with Scout first
+
+## Pipeline
+
+| Step | File | Action |
+|------|------|--------|
+| 1 | step-01-load-profile.md | Load GC1, check for existing amendments (GC4) |
+| 2 | step-02-generate-capabilities.md | Generate capabilities using standards + stack context |
+| 3 | step-03-web-enrichment.md | Enrich with web search for current best practices |
+| 4 | step-04-write-manifest.md | Write capabilities.yaml (GC2), surface limited-coverage warning if <20 |
+
+## Model Ownership
+
+The generated manifest is team-owned. On regeneration:
+- Amendments from Coach (GC4) are respected — removed capabilities stay removed
+- User-edited capabilities persist with `amended: true`
+- New capabilities are added alongside existing amendments
+
+## Instructions
+
+Load the first step to begin:
+
+```
+Load step: {project-root}/_bmad/bme/_gyre/workflows/model-generation/steps/step-01-load-profile.md
+```