convoke-agents 2.3.1 → 3.0.0

package/_bmad/bme/_gyre/compass-routing-reference.md

@@ -0,0 +1,168 @@
+# Compass Routing Reference — Gyre Pattern
+
+> **Status:** Authoritative | **Version:** 1.0 | **Created:** 2026-03-21
+>
+> This is the **authoritative** routing reference for the Gyre Pattern. All step-file Compass sections MUST reference this document for routing decisions.
+
+---
+
+## Gyre Overview
+
+The Gyre Pattern has 4 agents across 4 streams, connected by 4 handoff contracts:
+
+```
+                      ┌─────────────────────────────────────────────┐
+                      │            GYRE PATTERN                      │
+                      │         4 Streams · 4 Agents                 │
+                      └─────────────────────────────────────────────┘
+
+  ┌──────────┐    GC1    ┌──────────┐    GC2    ┌──────────┐    GC3    ┌──────────┐
+  │ Scout 🔎  │─────────▶│ Atlas 📐  │─────────▶│  Lens 🔬  │─────────▶│ Coach 🏋️  │
+  │  Detect   │ artifact │  Model   │ artifact │ Analyze  │ artifact │  Review  │
+  └──────────┘          └──────────┘          └──────────┘          └──────────┘
+                              ▲                                          │
+                              │                  GC4                     │
+                              └──────────────────────────────────────────┘
+                                            feedback
+```
+
+**Contract Types:**
+- **GC1–GC3** (forward flow): Artifact contracts — agent produces a schema-compliant artifact file
+- **GC4** (feedback loop): Coach amends the capabilities model; Atlas respects amendments on regeneration
+
+---
+
+## Routing Mechanisms
+
+Gyre uses a simpler routing model than Vortex — it's a linear pipeline with one feedback loop. Routing is primarily **action-driven** (what the user wants to do next) rather than **evidence-driven** (what evidence suggests).
+
+| Mechanism | Description | Contracts | Compass Row Pattern |
+|-----------|-------------|-----------|-------------------|
+| **Schema-driven** | Artifact produced, schema declares target | GC1–GC3 | "Your [artifact] is ready for [Agent]" |
+| **Feedback-driven** | Coach amendments feed back to Atlas | GC4 | "Model updated — regenerate to apply amendments" |
+| **Action-driven** | User chooses next workflow by intent | All | "If you want to [action], run [workflow]" |
+
+---
+
+## Handoff Contract Reference
+
+### Artifact Contracts (GC1–GC3)
+
+These contracts have schema definitions in `_bmad/bme/_gyre/contracts/`. Each artifact produced by the source agent must conform to the schema.
+
+| Contract | Flow | Schema File | Expected Artifact | Trigger Condition |
+|----------|------|-------------|-------------------|-------------------|
+| **GC1** | Scout 🔎 → Atlas 📐 | `contracts/gc1-stack-profile.md` | Stack Profile — technology categories, archetype, guard answers, confidence level | Stack detection complete; classification confirmed by user |
+| **GC2** | Atlas 📐 → Lens 🔬 | `contracts/gc2-capabilities-manifest.md` | Capabilities Manifest — ≥20 capabilities relevant to detected stack, each with domain, description, why-it-matters | Model generation complete; capabilities curated for the stack |
+| **GC3** | Lens 🔬 → Coach 🏋️ | `contracts/gc3-findings-report.md` | Findings Report — absence-based findings with severity, confidence, evidence, capability refs; cross-domain compounds | Gap analysis complete; all domains analyzed and correlated |
+
+### Feedback Contract (GC4)
+
+| Contract | Flow | Routing Type | Trigger Condition | What the Target Agent Receives |
+|----------|------|-------------|-------------------|-------------------------------|
+| **GC4** | Coach 🏋️ → Atlas 📐 | Feedback-driven | Coach captures model amendments (keep/remove/edit) and missed-gap feedback during review | Atlas receives: amendment list (capabilities to remove, edit, or add) + user feedback on missed gaps. Respected on next model regeneration. |
+
+---
+
+## Complete Routing Decision Matrix
+
+### Scout 🔎 — Detect (Stream 1)
+
+| Workflow | Route 1 | Route 2 | Route 3 |
+|----------|---------|---------|---------|
+| `stack-detection` | → Atlas 📐 `model-generation` — Stack Profile (GC1) ready for model generation | → Scout 🔎 `stack-detection` — Re-detect after project changes | → Coach 🏋️ `model-review` — Review existing model with new stack context |
+
+### Atlas 📐 — Model (Stream 2)
+
+| Workflow | Route 1 | Route 2 | Route 3 |
+|----------|---------|---------|---------|
+| `model-generation` | → Lens 🔬 `gap-analysis` — Capabilities Manifest (GC2) ready for analysis | → Coach 🏋️ `model-review` — Review and customize model before analysis | → Atlas 📐 `accuracy-validation` — Validate model quality before proceeding |
+| `accuracy-validation` | → Atlas 📐 `model-generation` — Iterate prompts if accuracy < 70% | → Lens 🔬 `gap-analysis` — Accuracy validated, proceed to analysis | |
+
+### Lens 🔬 — Analyze (Stream 3)
+
+| Workflow | Route 1 | Route 2 | Route 3 |
+|----------|---------|---------|---------|
+| `gap-analysis` | → Coach 🏋️ `model-review` — Findings Report (GC3) ready for review | → Lens 🔬 `delta-report` — Compare with previous run | → Atlas 📐 `model-generation` — Model seems wrong, regenerate |
+| `delta-report` | → Coach 🏋️ `model-review` — Review changes since last analysis | → Scout 🔎 `stack-detection` — Stack may have changed, re-detect | |
+
+### Coach 🏋️ — Review (Stream 4)
+
+| Workflow | Route 1 | Route 2 | Route 3 |
+|----------|---------|---------|---------|
+| `model-review` | → Atlas 📐 `model-generation` — Amendments captured (GC4), regenerate model | → Lens 🔬 `gap-analysis` — Model reviewed, proceed to analysis | → Scout 🔎 `full-analysis` — Run complete pipeline from scratch |
+
+---
+
+## Inter-Module Routing (Gyre → Vortex)
+
+Gyre findings can feed into Vortex product discovery:
+
+| If Gyre finds... | Consider in Vortex... | Agent | Why |
+|---|---|---|---|
+| Critical readiness gaps blocking launch | `product-vision` or `contextualize-scope` | Emma 🎯 | Readiness gaps may redefine product scope |
+| Findings that challenge assumptions | `hypothesis-engineering` | Liam 💡 | Readiness findings are testable hypotheses |
+| Feedback suggesting missing capabilities | `user-interview` | Isla 🔍 | Validate missed gaps with users |
+
+> **Note:** Inter-module routing is advisory. The user decides whether a Gyre finding warrants Vortex action.
+
+---
+
+## Compass Table Format
+
+All step-file Compass sections MUST use this uniform format:
+
+```markdown
+## Gyre Compass
+
+Based on what you just completed, here are your options:
+
+| If you want to... | Consider next... | Agent | Why |
+|---|---|---|---|
+| [action/intent] | [workflow-name] | [Agent Icon] | [rationale] |
+| [action/intent] | [workflow-name] | [Agent Icon] | [rationale] |
+| [action/intent] | [workflow-name] | [Agent Icon] | [rationale] |
+
+> **Note:** These are recommendations. You can run any Gyre workflow at any time.
+```
+
+**Rules:**
+- **2–3 rows** per Compass table
+- Agent display format: `AgentName Icon` (e.g., `Scout 🔎`, `Atlas 📐`)
+- Include inter-module routing rows only in Coach's final step (findings review complete)
+- `full-analysis` compass appears in step-05-review-findings only
+
+### Agent Display Reference
+
+| Agent | Display Format |
+|-------|---------------|
+| Scout | `Scout 🔎` |
+| Atlas | `Atlas 📐` |
+| Lens | `Lens 🔬` |
+| Coach | `Coach 🏋️` |
+
+---
+
+## Full Compass Table (used in step-05-review-findings of full-analysis)
+
+This comprehensive table appears only at the end of the full pipeline:
+
+| If you want to... | Consider next... | Agent | Why |
+|---|---|---|---|
+| Detect or re-detect your stack | stack-detection | Scout 🔎 | New project or stack has changed |
+| Generate or regenerate the model | model-generation | Atlas 📐 | First run or want fresh model |
+| Review your capabilities manifest | model-review | Coach 🏋️ | Customize the model to your stack |
+| Run gap analysis | gap-analysis | Lens 🔬 | Find what's missing |
+| See what changed since last run | delta-report | Lens 🔬 | Track progress over time |
+| Run the full pipeline | full-analysis | Scout 🔎 | Complete end-to-end analysis |
+| Validate model accuracy | accuracy-validation | Atlas 📐 | Pre-pilot quality gate |
+
+> **Note:** These are recommendations. You can run any Gyre workflow at any time.
+
+---
+
+## Version History
+
+| Version | Date | Changes |
+|---------|------|---------|
+| 1.0 | 2026-03-21 | Initial creation — 4 contracts, 7 workflows, 4 agents, inter-module routing |

package/_bmad/bme/_gyre/config.yaml

@@ -0,0 +1,22 @@
+submodule_name: _gyre
+description: Gyre Pattern - Production readiness discovery through stack analysis, contextual model generation, and absence detection
+module: bme
+output_folder: '{project-root}/_bmad-output/gyre-artifacts'
+agents:
+  - stack-detective
+  - model-curator
+  - readiness-analyst
+  - review-coach
+workflows:
+  - full-analysis
+  - stack-detection
+  - model-generation
+  - model-review
+  - gap-analysis
+  - delta-report
+  - accuracy-validation
+version: 1.0.0
+user_name: '{user}'
+communication_language: en
+party_mode_enabled: true
+core_module: bme

package/_bmad/bme/_gyre/contracts/gc1-stack-profile.md

@@ -0,0 +1,152 @@
+# GC1: Stack Profile — Schema Definition
+
+> **Contract:** GC1 | **Type:** Artifact | **Flow:** Scout → Atlas, Lens
+>
+> This schema defines the structure for the Stack Profile produced by the stack-detection workflow. The Stack Profile captures technology classifications — NOT file contents, paths, or secrets.
+
+## Frontmatter Schema
+
+```yaml
+---
+contract: GC1
+type: artifact
+source_agent: scout
+source_workflow: stack-detection
+target_agents: [atlas, lens]
+input_artifacts: []
+created: YYYY-MM-DD
+---
+```
+
+### Frontmatter Field Reference
+
+| Field | Required | Type | Description |
+|-------|----------|------|-------------|
+| `contract` | Yes | string | Always `GC1` |
+| `type` | Yes | string | Always `artifact` |
+| `source_agent` | Yes | string | Always `scout` |
+| `source_workflow` | Yes | string | Always `stack-detection` |
+| `target_agents` | Yes | array | Agent IDs that consume this artifact: `[atlas, lens]` |
+| `input_artifacts` | Yes | array | Empty array `[]` — GC1 is the first contract in the Gyre chain |
+| `created` | Yes | date | ISO date when artifact was created |
+
+---
+
+## Privacy Rule
+
+**GC1 must contain technology categories and classifications only.**
+
+It must NOT contain:
+- File contents
+- File paths
+- Version numbers
+- Dependency counts
+- Dependency names
+- Secrets, tokens, or credentials
+
+This is the privacy boundary. Agents can read any file during detection, but the committed artifact carries only category-level metadata. Everything downstream of GC1 works with this metadata.
+
+---
+
+## Body Schema
+
+The Stack Profile is written to `.gyre/stack-profile.yaml` with the following structure:
+
+```yaml
+stack_profile:
+  primary_language: string        # e.g., "Go", "Node.js", "Python"
+  primary_framework: string       # e.g., "Express", "Gin", "FastAPI"
+  secondary_stacks: string[]      # e.g., ["Python sidecar"] — empty if single stack
+  container_orchestration: string  # e.g., "Kubernetes", "ECS", "Docker Compose", "none"
+  ci_cd_platform: string          # e.g., "GitHub Actions", "GitLab CI", "Jenkins"
+  observability_tooling: string[] # e.g., ["OpenTelemetry", "Prometheus"]
+  cloud_provider: string          # e.g., "AWS", "GCP", "Azure", "multi-cloud"
+  communication_protocol: string  # e.g., "HTTP/REST", "gRPC", "message-queue"
+  guard_answers:                  # only populated if guard questions were asked
+    deployment_model: string      # "container-based" | "serverless" | "bare-metal"
+    protocol: string              # confirmed communication protocol
+    custom: object                # any additional guard answers
+  detection_confidence: string    # "high" | "medium" | "low"
+  detection_summary: string       # human-readable summary of what was found
+```
+
+### Field Reference
+
+| Field | Required | Type | Description |
+|-------|----------|------|-------------|
+| `primary_language` | Yes | string | Primary programming language detected |
+| `primary_framework` | Yes | string | Primary framework detected (or "none" if bare language) |
+| `secondary_stacks` | Yes | array | Secondary stacks in monorepo. Empty array if single-stack project |
+| `container_orchestration` | Yes | string | Container platform. "none" if no container usage detected |
+| `ci_cd_platform` | Yes | string | CI/CD platform. "none" if no CI config detected |
+| `observability_tooling` | Yes | array | Observability tools found. Empty array if none detected |
+| `cloud_provider` | Yes | string | Cloud provider. "none" if no cloud indicators found |
+| `communication_protocol` | Yes | string | Primary communication pattern |
+| `guard_answers` | No | object | Present only if guard questions were asked. Contains confirmed answers |
+| `guard_answers.deployment_model` | No | string | Confirmed deployment model from guard question |
+| `guard_answers.protocol` | No | string | Confirmed communication protocol from guard question |
+| `guard_answers.custom` | No | object | Additional guard answers not covered by standard fields |
+| `detection_confidence` | Yes | string | Overall confidence: "high", "medium", or "low" |
+| `detection_summary` | Yes | string | Human-readable 1-3 sentence summary of the detected stack |
+
+---
+
+## Artifact Location
+
+- **Path:** `.gyre/stack-profile.yaml` (relative to project root, or service root in monorepo)
+- **Directory creation:** `.gyre/` is created on first run if it doesn't exist (FR42)
+- **Concurrency:** `.gyre/.lock` file prevents concurrent analysis (NFR13)
+- **Atomicity:** Write to temp file first, then rename to final path
+
+---
+
+## Downstream Consumption
+
+| Consumer | Purpose |
+|----------|---------|
+| **Atlas** (model-curator) | Uses stack classification to generate contextually relevant capabilities for model generation |
+| **Lens** (readiness-analyst) | Uses stack classification for domain-specific analysis targeting — which directories to search, what patterns to match |
+
+---
+
+## Example
+
+```yaml
+---
+contract: GC1
+type: artifact
+source_agent: scout
+source_workflow: stack-detection
+target_agents: [atlas, lens]
+input_artifacts: []
+created: 2026-03-22
+---
+
+stack_profile:
+  primary_language: "Node.js"
+  primary_framework: "Express"
+  secondary_stacks: []
+  container_orchestration: "Kubernetes"
+  ci_cd_platform: "GitHub Actions"
+  observability_tooling: ["OpenTelemetry", "Prometheus"]
+  cloud_provider: "AWS"
+  communication_protocol: "HTTP/REST"
+  guard_answers:
+    deployment_model: "container-based"
+  detection_confidence: "high"
+  detection_summary: "Node.js Express web service deployed on AWS EKS via GitHub Actions. Instrumented with OpenTelemetry and Prometheus. REST API."
+```
+
+---
+
+## Validation Rules
+
+A valid GC1 artifact must:
+
+1. Have all required frontmatter fields present and correctly typed
+2. Have all required body fields present and non-empty
+3. Contain NO file paths, file contents, version numbers, dependency names, or secrets
+4. Have `detection_confidence` as one of: "high", "medium", "low"
+5. Have `guard_answers` present only if guard questions were actually asked
+6. Have `secondary_stacks` as an array (empty if single-stack)
+7. Have `observability_tooling` as an array (empty if none detected)

package/_bmad/bme/_gyre/contracts/gc2-capabilities-manifest.md

@@ -0,0 +1,189 @@
+# GC2: Capabilities Manifest — Schema Definition
+
+> **Contract:** GC2 | **Type:** Artifact | **Flow:** Atlas → Lens, Coach
+>
+> This schema defines the structure for the Capabilities Manifest produced by the model-generation workflow. The manifest contains contextual capabilities relevant to the detected stack — NOT source code, file contents, or secrets.
+
+## Frontmatter Schema
+
+```yaml
+---
+contract: GC2
+type: artifact
+source_agent: atlas
+source_workflow: model-generation
+target_agents: [lens, coach]
+input_artifacts: [GC1]
+created: YYYY-MM-DD
+---
+```
+
+### Frontmatter Field Reference
+
+| Field | Required | Type | Description |
+|-------|----------|------|-------------|
+| `contract` | Yes | string | Always `GC2` |
+| `type` | Yes | string | Always `artifact` |
+| `source_agent` | Yes | string | Always `atlas` |
+| `source_workflow` | Yes | string | Always `model-generation` |
+| `target_agents` | Yes | array | Agent IDs that consume this artifact: `[lens, coach]` |
+| `input_artifacts` | Yes | array | `[GC1]` — requires Stack Profile |
+| `created` | Yes | date | ISO date when artifact was created |
+
+---
+
+## Artifact Safety Rule
+
+**GC2 must not contain source code, file contents, or secrets (NFR9).**
+
+Capabilities describe WHAT should exist (categories, practices, standards) — not WHAT currently exists in the codebase. Evidence comparison is Lens's job (GC3), not Atlas's.
+
+---
+
+## Body Schema
+
+The Capabilities Manifest is written to `.gyre/capabilities.yaml` with the following structure:
+
+```yaml
+gyre_manifest:
+  version: string                 # manifest schema version, e.g., "1.0"
+  generated_at: ISO-8601          # generation timestamp
+  stack_summary: string           # one-line stack description from GC1
+  capability_count: integer       # total number of capabilities (excluding removed)
+  limited_coverage: boolean       # true if <20 capabilities generated
+  capabilities:
+    - id: string                  # kebab-case identifier, e.g., "health-check-liveness"
+      category: string            # "observability" | "deployment" | "reliability" | "security"
+      name: string                # human-readable name
+      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: boolean            # true if user-modified via Coach review (GC4)
+      removed: boolean            # true if user removed via Coach review (GC4)
+  provenance:
+    standards_referenced: string[]  # e.g., ["DORA", "OpenTelemetry", "Google PRR"]
+    web_search_performed: boolean
+    web_search_date: ISO-8601       # null if web search not performed
+```
+
+### Field Reference
+
+| Field | Required | Type | Description |
+|-------|----------|------|-------------|
+| `version` | Yes | string | Schema version for future breaking changes (NFR17) |
+| `generated_at` | Yes | string | ISO-8601 timestamp of generation |
+| `stack_summary` | Yes | string | One-line description of detected stack |
+| `capability_count` | Yes | integer | Total active capabilities (excluding removed) |
+| `limited_coverage` | Yes | boolean | True if fewer than 20 capabilities generated |
+| `capabilities` | Yes | array | List of capability objects |
+| `capabilities[].id` | Yes | string | Unique kebab-case identifier |
+| `capabilities[].category` | Yes | string | Domain category |
+| `capabilities[].name` | Yes | string | Human-readable capability name |
+| `capabilities[].description` | Yes | string | 1-3 sentence description with stack-specific context |
+| `capabilities[].source` | Yes | string | Origin: "standard", "practice", or "reasoning" |
+| `capabilities[].relevance` | Yes | string | Why this capability matters for this specific stack |
+| `capabilities[].amended` | Yes | boolean | True if modified by user during Coach review |
+| `capabilities[].removed` | Yes | boolean | True if removed by user during Coach review |
+| `provenance` | Yes | object | Generation metadata |
+| `provenance.standards_referenced` | Yes | array | Industry standards used |
+| `provenance.web_search_performed` | Yes | boolean | Whether web search enrichment was done |
+| `provenance.web_search_date` | No | string | ISO-8601 date of web search, null if not performed |
+
+---
+
+## Capability Categories
+
+| Category | Description | Typical Count |
+|----------|-------------|:------------:|
+| `observability` | Logging, tracing, metrics, health checks, alerting | 6-10 |
+| `deployment` | CI/CD, containers, orchestration, rollback, IaC | 5-8 |
+| `reliability` | Graceful shutdown, circuit breakers, rate limiting, fault tolerance | 4-6 |
+| `security` | Secrets management, vulnerability scanning, network policies, auth | 3-5 |
+
+---
+
+## Capability Sources
+
+| Source | Meaning | Examples |
+|--------|---------|---------|
+| `standard` | Derived from a named industry framework | DORA metrics, OpenTelemetry SDK, Google PRR checklist |
+| `practice` | Common industry practice found via web search or domain expertise | Structured logging with correlation IDs, multi-stage Docker builds |
+| `reasoning` | Derived from stack analysis — Atlas inferred this is relevant | "gRPC health checking protocol" inferred from gRPC + Kubernetes stack |
+
+---
+
+## Artifact Location
+
+- **Path:** `.gyre/capabilities.yaml` (relative to project root, or service root in monorepo)
+- **Caching:** The manifest file IS the cache — re-runs load it, no regeneration unless explicit (NFR10)
+- **Amendment persistence:** Coach writes amendments directly to this file via GC4
+
+---
+
+## Downstream Consumption
+
+| Consumer | Purpose |
+|----------|---------|
+| **Lens** (readiness-analyst) | Compares each capability against filesystem evidence to identify absences — what's missing, not just what's misconfigured |
+| **Coach** (review-coach) | Presents capabilities for user review — keep/remove/edit. Captures amendments written back via GC4 |
+
+---
+
+## Example
+
+```yaml
+---
+contract: GC2
+type: artifact
+source_agent: atlas
+source_workflow: model-generation
+target_agents: [lens, coach]
+input_artifacts: [GC1]
+created: 2026-03-22
+---
+
+gyre_manifest:
+  version: "1.0"
+  generated_at: "2026-03-22T14:30:00Z"
+  stack_summary: "Node.js Express web service on AWS EKS via GitHub Actions"
+  capability_count: 24
+  limited_coverage: false
+  capabilities:
+    - id: "structured-logging"
+      category: "observability"
+      name: "Structured JSON Logging"
+      description: "Application logs in structured JSON format with correlation IDs for request tracing. Essential for EKS workloads where CloudWatch Logs Insights or Elasticsearch are used for log analysis."
+      source: "standard"
+      relevance: "Node.js services on EKS need structured logs for CloudWatch Logs Insights queries and cross-service correlation."
+      amended: false
+      removed: false
+    - id: "health-check-liveness"
+      category: "observability"
+      name: "Kubernetes Liveness Probe"
+      description: "HTTP endpoint (typically /healthz) that Kubernetes uses to detect stuck containers and restart them. Must check application responsiveness, not downstream dependencies."
+      source: "standard"
+      relevance: "EKS requires liveness probes to auto-heal unresponsive pods. Express apps need a lightweight /healthz endpoint."
+      amended: false
+      removed: false
+  provenance:
+    standards_referenced: ["DORA", "OpenTelemetry", "Google PRR"]
+    web_search_performed: true
+    web_search_date: "2026-03-22"
+```
+
+---
+
+## Validation Rules
+
+A valid GC2 artifact must:
+
+1. Have all required frontmatter fields present and correctly typed
+2. Have all required body fields present and non-empty
+3. Contain NO source code, file contents, or secrets
+4. Have `version` as a string (semantic version format)
+5. Have each capability with all required fields present
+6. Have `category` as one of: "observability", "deployment", "reliability", "security"
+7. Have `source` as one of: "standard", "practice", "reasoning"
+8. Have unique `id` values across all capabilities
+9. Have `capability_count` matching the actual count of non-removed capabilities
+10. Have `limited_coverage` set to true if capability_count < 20