convoke-agents 2.4.0 → 3.0.1

package/_bmad/bme/_gyre/workflows/model-review/steps/step-01-load-context.md

@@ -0,0 +1,86 @@
+---
+step: 1
+workflow: model-review
+title: Load Context
+implements: Stories 4.4, 4.5
+---
+
+# Step 1: Load Context
+
+Load artifacts, display existing feedback, and detect whether the user deferred a review previously.
+
+## MANDATORY EXECUTION RULES
+
+- Check for GC2 (capabilities.yaml) — REQUIRED for any review
+- Check for GC3 (findings.yaml) — REQUIRED for findings review, optional for model-only review
+- Check for existing feedback.yaml — display previous entries if present (FR53)
+- Check for deferred review flag — remind user if review was deferred (FR55)
+
+## EXECUTION
+
+### 1. Load GC2 (Capabilities Manifest)
+
+Read `.gyre/capabilities.yaml`. If missing:
+
+```
+❌ No capabilities manifest found at .gyre/capabilities.yaml
+
+Coach needs a capabilities model to review. Please run model generation first:
+- Activate Atlas (Model Curator) and run [GM] Generate Model
+- Or run [FA] Full Analysis to generate everything from scratch
+```
+
+Then STOP — do not proceed.
+
+### 2. Load GC3 (Findings Report) — Optional
+
+Read `.gyre/findings.yaml`. If missing, note that findings review is unavailable but model review can proceed.
+
+### 3. Display Existing Feedback (FR53)
+
+Read `.gyre/feedback.yaml` if it exists. If it has entries, present them:
+
+```
+### Previous Feedback
+
+Your team has previously reported:
+
+| Date | Reporter | Type | Description |
+|------|----------|------|-------------|
+| [timestamp] | [reporter] | [type] | [description] |
+
+These entries inform model improvement. You can add more during this review.
+```
+
+### 4. Check Deferred Review Flag (FR55)
+
+Read `.gyre/capabilities.yaml` frontmatter. If `review_deferred: true` is present:
+
+```
+💡 You deferred reviewing your capabilities manifest last time — would you like to review now?
+```
+
+### 5. Ask Review Mode
+
+Present the user with options:
+
+```
+What would you like to review?
+
+1. **Review Model** — Walk through your capabilities one by one (keep/remove/edit/add)
+2. **Review Findings** — See findings severity-first, then capture feedback
+3. **Both** — Findings first, then model walkthrough, then feedback
+
+Or type "skip" to go straight to feedback capture.
+```
+
+Wait for user input. Based on selection, proceed to the appropriate step.
+
+---
+
+## NEXT STEP
+
+Based on user selection:
+- Review Model or Both → Load step: {project-root}/_bmad/bme/_gyre/workflows/model-review/steps/step-02-walkthrough.md
+- Review Findings → Present findings severity-first (use the format from gap-analysis step-05), then skip to step-04
+- Skip → Load step: {project-root}/_bmad/bme/_gyre/workflows/model-review/steps/step-04-capture-feedback.md

package/_bmad/bme/_gyre/workflows/model-review/steps/step-02-walkthrough.md

@@ -0,0 +1,116 @@
+---
+step: 2
+workflow: model-review
+title: Capabilities Walkthrough
+implements: Story 4.2 (FR24, FR25, FR27)
+---
+
+# Step 2: Capabilities Walkthrough
+
+Walk through each capability in the manifest. The user decides what stays, what goes, and what changes.
+
+## MANDATORY EXECUTION RULES
+
+- Present capabilities grouped by category (observability, deployment, reliability, security)
+- For each capability: show name, description, category, source, relevance
+- Accept conversational responses: "keep", "remove", "edit", "skip remaining"
+- Track all amendments in memory for step 3
+- Never push opinions — present and let the user decide (FR24)
+- User can add new capabilities by describing them conversationally (FR25)
+
+## EXECUTION
+
+### 1. Present Category Overview
+
+Before walking through, show a summary:
+
+```
+### Your Capabilities Model
+
+| Category | Count |
+|----------|:-----:|
+| Observability | [N] |
+| Deployment | [N] |
+| Reliability | [N] |
+| Security | [N] |
+| **Total** | **[N]** |
+
+I'll walk through each capability. For each one, you can:
+- **Keep** — no changes (just press Enter or say "keep")
+- **Remove** — exclude from future analysis
+- **Edit** — change the description or category
+- **Add** — describe a new capability to add
+- **Skip remaining** — keep everything else as-is
+
+Let's start with [first category].
+```
+
+### 2. Per-Capability Presentation
+
+For each capability (grouped by category):
+
+```
+**[N of total] [capability-name]** ([category])
+[description]
+_Source: [static-analysis|contextual-model] | Relevance: [relevance explanation]_
+
+Keep / Remove / Edit?
+```
+
+### 3. Handle Responses
+
+**Keep:** Mark as unchanged, move to next.
+
+**Remove:** Record `removed: true` amendment. Confirm:
+```
+✓ Marked [capability-name] for removal. It won't appear in future analyses.
+```
+
+**Edit:** Ask what to change. Accept conversational edits:
+- "Change the description to..." → record new description with `amended: true`
+- "Move to [category]" → record category change with `amended: true`
+- "Change the name to..." → record name change with `amended: true`
+
+Confirm each edit:
+```
+✓ Updated [capability-name]: [what changed]
+```
+
+**Add:** User describes a new capability conversationally. Coach creates the entry:
+```
+I'll add that. Here's what I have:
+
+**[new-capability-name]** ([category])
+[description based on user input]
+_Source: user-added_
+
+Does that look right?
+```
+
+**Skip remaining:** Confirm count remaining, mark all as kept:
+```
+✓ Keeping the remaining [N] capabilities as-is.
+```
+
+### 4. Walkthrough Summary
+
+After all capabilities reviewed:
+
+```
+### Review Summary
+
+- ✅ Kept: [N] capabilities
+- ❌ Removed: [N] capabilities
+- ✏️ Edited: [N] capabilities
+- ➕ Added: [N] capabilities
+
+Ready to apply these changes?
+```
+
+Wait for confirmation before proceeding.
+
+---
+
+## NEXT STEP
+
+Load step: {project-root}/_bmad/bme/_gyre/workflows/model-review/steps/step-03-apply-amendments.md

package/_bmad/bme/_gyre/workflows/model-review/steps/step-03-apply-amendments.md

@@ -0,0 +1,92 @@
+---
+step: 3
+workflow: model-review
+title: Apply Amendments
+implements: Story 4.2 (FR25, FR26, FR27), Story 4.3
+---
+
+# Step 3: Apply Amendments
+
+Write amendments directly to capabilities.yaml. This is the GC4 (Feedback Loop) mechanism — amendments are stored as flags on the capabilities themselves, not in a separate file.
+
+## MANDATORY EXECUTION RULES
+
+- Read current `.gyre/capabilities.yaml` before writing
+- Apply amendments directly to the capabilities array
+- Set `removed: true` on removed capabilities (FR27 — model subtraction)
+- Set `amended: true` on edited capabilities, preserving original values as `original_*` fields
+- Add new capabilities with `source: "user-added"` and `amended: true`
+- Update the frontmatter: set `last_reviewed: [ISO date]`, `review_deferred: false`
+- Amended artifacts must NOT contain source code, file contents, or secrets (NFR9)
+- Write the file atomically — do not leave partial state
+
+## EXECUTION
+
+### 1. Read Current Manifest
+
+Load `.gyre/capabilities.yaml` and parse the capabilities array.
+
+### 2. Apply Removals
+
+For each capability marked for removal:
+- Add `removed: true` to the capability entry
+- Add `removed_at: [ISO date]` for audit trail
+- Do NOT delete the entry — keep it for amendment persistence (FR26)
+
+### 3. Apply Edits
+
+For each capability marked for edit:
+- Set `amended: true`
+- Set `amended_at: [ISO date]`
+- Store original values: `original_description`, `original_name`, `original_category` (only the fields that changed)
+- Apply the new values
+
+### 4. Add New Capabilities
+
+For each new capability from the walkthrough:
+- Generate a unique ID following the pattern: `[category-prefix]-[NNN]` (e.g., `obs-custom-001`)
+- Set `source: "user-added"`
+- Set `amended: true`
+- Set `amended_at: [ISO date]`
+
+### 5. Update Frontmatter
+
+Update the capabilities.yaml frontmatter:
+- Set `last_reviewed: [ISO date]`
+- Set `review_deferred: false`
+- Increment `amendment_count` (or set to 1 if first review)
+
+### 6. Write Updated Manifest
+
+Write the complete updated manifest back to `.gyre/capabilities.yaml`.
+
+Confirm to user:
+
+```
+✅ Amendments applied to .gyre/capabilities.yaml
+
+- [N] capabilities removed (will be excluded from future analysis)
+- [N] capabilities edited
+- [N] new capabilities added
+- Amendment count: [N]
+
+These amendments will persist when Atlas regenerates the model.
+```
+
+## ERROR RECOVERY
+
+If write fails:
+```
+❌ Could not write amendments to .gyre/capabilities.yaml
+
+Your amendments have been captured but not saved. Options:
+a) Retry writing
+b) Display amendments as YAML so you can apply manually
+c) Exit without saving
+```
+
+---
+
+## NEXT STEP
+
+Load step: {project-root}/_bmad/bme/_gyre/workflows/model-review/steps/step-04-capture-feedback.md

package/_bmad/bme/_gyre/workflows/model-review/steps/step-04-capture-feedback.md

@@ -0,0 +1,107 @@
+---
+step: 4
+workflow: model-review
+title: Capture Feedback
+implements: Story 4.4 (FR28, FR29, FR30)
+---
+
+# Step 4: Capture Feedback
+
+Prompt the user for missed-gap feedback and persist it for team-wide model improvement.
+
+## MANDATORY EXECUTION RULES
+
+- Always prompt: "Did Gyre miss anything you know about?" (FR28)
+- Persist feedback to `.gyre/feedback.yaml` with timestamp (FR29)
+- Explain commit workflow for team sharing (FR30)
+- Feedback entries: timestamp, reporter, type, description, domain
+- Append to existing feedback — never overwrite previous entries
+
+## EXECUTION
+
+### 1. Prompt for Feedback
+
+```
+### Feedback
+
+Did Gyre miss anything you know about? For example:
+- A capability your stack has that wasn't in the model
+- A gap Gyre didn't detect that you know exists
+- A severity that feels wrong based on your experience
+
+Type your feedback, or "none" to skip.
+```
+
+### 2. Capture Feedback Entry
+
+For each piece of feedback the user provides, create an entry:
+
+```yaml
+- timestamp: "[ISO-8601]"
+  reporter: "{user_name}"
+  type: "[missed-capability|missed-gap|severity-adjustment|other]"
+  description: "[user's feedback in their words]"
+  domain: "[observability|deployment|reliability|security|general]"
+```
+
+Classify the type based on the user's response:
+- Mentions a capability not in the model → `missed-capability`
+- Mentions a gap not in findings → `missed-gap`
+- Disagrees with severity → `severity-adjustment`
+- Everything else → `other`
+
+Ask the user to classify the domain if unclear, or infer from context.
+
+### 3. Ask for More
+
+After each entry:
+```
+✓ Captured. Anything else? (or "done" to finish)
+```
+
+Continue until user says "done", "none", or similar.
+
+### 4. Write Feedback File
+
+If there are new feedback entries, append to `.gyre/feedback.yaml`:
+
+```yaml
+# If file doesn't exist yet, create with header:
+---
+contract: GC4
+type: artifact
+source_agent: coach
+target_agents: [atlas]
+created: [date of first entry]
+updated: [today's date]
+---
+
+feedback:
+  # [existing entries preserved]
+  - timestamp: "..."
+    reporter: "..."
+    type: "..."
+    description: "..."
+    domain: "..."
+```
+
+If file exists, update the `updated` date in frontmatter and append new entries to the feedback array.
+
+### 5. Explain Team Sharing (FR30)
+
+```
+✅ Feedback saved to .gyre/feedback.yaml
+
+💡 **Tip:** Commit `feedback.yaml` to your repository so your team's knowledge improves the model for everyone. Atlas will incorporate this feedback when regenerating capabilities.
+```
+
+If no feedback was provided:
+```
+No feedback to save — you can always provide feedback later by running Coach again.
+```
+
+---
+
+## NEXT STEP
+
+Load step: {project-root}/_bmad/bme/_gyre/workflows/model-review/steps/step-05-summary.md

package/_bmad/bme/_gyre/workflows/model-review/steps/step-05-summary.md

@@ -0,0 +1,60 @@
+---
+step: 5
+workflow: model-review
+title: Review Summary & Compass
+implements: Story 4.7
+---
+
+# Step 5: Review Summary & Compass
+
+Present a summary of the review session and route the user to their next action.
+
+## EXECUTION
+
+### 1. Session Summary
+
+```
+## Review Complete
+
+| Action | Count |
+|--------|:-----:|
+| Capabilities kept | [N] |
+| Capabilities removed | [N] |
+| Capabilities edited | [N] |
+| Capabilities added | [N] |
+| Feedback entries | [N] |
+
+Artifacts updated:
+- `.gyre/capabilities.yaml` — [updated if amendments / unchanged if no amendments]
+- `.gyre/feedback.yaml` — [updated if feedback / unchanged if no feedback]
+```
+
+### 2. Re-Analysis Recommendation
+
+If capabilities were removed or added:
+```
+💡 Since you changed your capabilities model, consider re-running gap analysis to get updated findings based on your customized model.
+```
+
+### 3. Gyre Compass
+
+```
+---
+
+## What's Next?
+
+| If you want to... | Consider next... | Agent | Why |
+|---|---|---|---|
+| Re-run analysis with your customized model | gap-analysis | Lens 🔬 | Updated findings based on your amendments |
+| Detect or re-detect your stack | stack-detection | Scout 🔎 | New project or stack has changed |
+| Generate a fresh model from scratch | model-generation | Atlas 📐 | Discard amendments and start over |
+| 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 |
+| Share findings with your team | — | — | Commit .gyre/ directory to your repository |
+
+> **Note:** These are recommendations. You can run any Gyre workflow at any time.
+```
+
+---
+
+Written to `.gyre/capabilities.yaml` and `.gyre/feedback.yaml`

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

@@ -0,0 +1,41 @@
+---
+name: model-review
+agent: review-coach
+title: Model Review & Amendment
+description: Walk through capabilities manifest and findings, capture amendments and feedback
+steps: 5
+implements: Epic 4 (Stories 4.2, 4.4, 4.5)
+---
+
+# Model Review & Amendment Workflow
+
+Coach guides the user through their capabilities manifest and findings report. The user can keep, remove, edit, or add capabilities conversationally. Feedback on missed gaps is captured and persisted.
+
+## Prerequisites
+
+- GC2 (Capabilities Manifest) at `.gyre/capabilities.yaml` — required for model review
+- GC3 (Findings Report) at `.gyre/findings.yaml` — required for findings review (optional if only reviewing model)
+
+## Pipeline
+
+| Step | File | Action |
+|------|------|--------|
+| 1 | step-01-load-context.md | Load artifacts, display existing feedback, detect deferred review |
+| 2 | step-02-walkthrough.md | Walk through capabilities one by one — keep/remove/edit/add |
+| 3 | step-03-apply-amendments.md | Write amendments to capabilities.yaml with flags |
+| 4 | step-04-capture-feedback.md | Prompt for missed gaps, persist to feedback.yaml |
+| 5 | step-05-summary.md | Present review summary and compass routing |
+
+## Mode Selection
+
+When activated, Coach asks which review the user wants:
+
+1. **Review Model** — walk through capabilities manifest (steps 1-5)
+2. **Review Findings** — present findings severity-first, then capture feedback (steps 1, 4, 5 with findings presentation)
+3. **Both** — full review: findings first, then model walkthrough, then feedback
+
+## Error Recovery
+
+- If GC2 missing: inform user to run model-generation first, offer to launch Atlas
+- If GC3 missing and user wants findings review: inform user to run gap-analysis first, offer to launch Lens
+- If amendment write fails: present what was captured so far, offer to retry

package/_bmad/bme/_gyre/workflows/stack-detection/steps/step-01-scan-filesystem.md

@@ -0,0 +1,176 @@
+---
+step: 1
+workflow: stack-detection
+title: Scan Filesystem
+---
+
+# Step 1: Scan Filesystem
+
+Discover technology indicators by examining the project's files. All detection is static — no code execution, no dependency installation.
+
+## MANDATORY EXECUTION RULES
+
+- Use Claude Code tools (Glob, Grep, Read) — do NOT ask the user to provide this information
+- Report findings with evidence — every detection must cite a specific file or pattern
+- Do NOT read file contents into the Stack Profile — only record technology categories
+- Scan breadth-first: discover what exists before diving deep into any single technology
+
+## SCAN SEQUENCE
+
+Execute the following scans. For each category, record what was found and what was NOT found.
+
+### 1. Package Manifests (Primary Language/Framework)
+
+**Glob** for these files at project root and one level deep:
+- `package.json`, `package-lock.json`, `yarn.lock`, `pnpm-lock.yaml` → Node.js ecosystem
+- `go.mod`, `go.sum` → Go
+- `requirements.txt`, `setup.py`, `pyproject.toml`, `Pipfile`, `poetry.lock` → Python
+- `Cargo.toml`, `Cargo.lock` → Rust
+- `pom.xml`, `build.gradle`, `build.gradle.kts` → Java/Kotlin (JVM)
+- `Gemfile`, `Gemfile.lock` → Ruby
+- `composer.json` → PHP
+- `*.csproj`, `*.sln` → .NET/C#
+- `mix.exs` → Elixir
+- `pubspec.yaml` → Dart/Flutter
+
+**Read** the primary manifest to identify:
+- Framework (e.g., Express, Next.js, Django, Spring Boot, Rails, Gin, Actix)
+- Key dependencies that indicate architecture choices
+
+### 2. Container & Orchestration
+
+**Glob** for:
+- `Dockerfile`, `Dockerfile.*`, `*.dockerfile` → Container usage
+- `docker-compose.yaml`, `docker-compose.yml`, `compose.yaml` → Docker Compose
+- `k8s/`, `kubernetes/`, `manifests/`, `helm/`, `charts/` → Kubernetes
+- `ecs-task-definition.json`, `apprunner.yaml` → AWS ECS/App Runner
+- `fly.toml` → Fly.io
+- `render.yaml` → Render
+- `Procfile` → Heroku-style platforms
+
+### 3. CI/CD Platform
+
+**Glob** for:
+- `.github/workflows/*.yml`, `.github/workflows/*.yaml` → GitHub Actions
+- `.gitlab-ci.yml` → GitLab CI
+- `Jenkinsfile` → Jenkins
+- `.circleci/config.yml` → CircleCI
+- `azure-pipelines.yml` → Azure DevOps
+- `bitbucket-pipelines.yml` → Bitbucket Pipelines
+- `.travis.yml` → Travis CI
+
+### 4. Observability Tooling
+
+**Grep** across the project for:
+- `opentelemetry`, `@opentelemetry`, `otel` → OpenTelemetry
+- `prometheus`, `prom-client` → Prometheus
+- `datadog`, `dd-trace` → Datadog
+- `newrelic` → New Relic
+- `sentry` → Sentry (error tracking)
+- `grafana` → Grafana
+- `elastic`, `elasticsearch`, `kibana` → ELK Stack
+- `winston`, `pino`, `bunyan`, `log4j`, `logback`, `zap`, `zerolog` → Structured logging
+
+**Glob** for config files:
+- `otel-collector-config.yaml` → OpenTelemetry Collector
+- `prometheus.yml` → Prometheus config
+- `datadog.yaml` → Datadog Agent config
+
+### 5. Cloud Provider
+
+**Glob** for:
+- `terraform/`, `*.tf` → Terraform (then **Grep** for `provider "aws"`, `provider "google"`, `provider "azurerm"`)
+- `cloudformation/`, `template.yaml`, `template.json` → AWS CloudFormation
+- `pulumi/`, `Pulumi.yaml` → Pulumi
+- `serverless.yml`, `serverless.yaml` → Serverless Framework
+- `cdk.json` → AWS CDK
+- `firebase.json` → Firebase/GCP
+- `app.yaml` (with `runtime:`) → Google App Engine
+
+**Grep** for provider SDK imports:
+- `aws-sdk`, `@aws-sdk`, `boto3` → AWS
+- `@google-cloud`, `google.cloud` → GCP
+- `@azure`, `azure-` → Azure
+
+### 6. Communication Protocol
+
+**Grep** for:
+- `*.proto` files, `grpc`, `@grpc` → gRPC
+- `graphql`, `apollo`, `@apollo` → GraphQL
+- `express`, `fastify`, `gin`, `flask`, `django.urls`, REST patterns → HTTP/REST
+- `amqp`, `rabbitmq`, `@nestjs/microservices` → Message queues (AMQP)
+- `kafka`, `kafkajs` → Apache Kafka
+- `redis`, `ioredis`, `bull` → Redis (pub/sub or queues)
+- `socket.io`, `ws`, `websocket` → WebSocket
+
+### 7. Monorepo / Multi-Service Detection (FR1b, FR51)
+
+After completing scans 1-6, check if the project contains multiple independent services:
+
+**Detection criteria:** A service root is a directory that contains BOTH:
+- Its own package manifest (package.json, go.mod, requirements.txt, etc.)
+- Its own deployment config (Dockerfile, k8s manifest, serverless.yml, etc.)
+
+**Glob** for package manifests at depth 1-2:
+- `*/package.json`, `*/go.mod`, `*/requirements.txt`, `*/Cargo.toml`, `*/pom.xml`
+- `*/*/package.json`, `*/*/go.mod`, etc. (for `services/api/`, `packages/worker/` patterns)
+
+For each manifest found, check if a deployment config exists in the same directory or its parent.
+
+**If ≥2 service roots detected:**
+
+Present the services conversationally and ask the user to select one:
+
+```
+I detected multiple services in this project:
+
+| # | Service Root | Language | Has Deployment Config |
+|---|-------------|----------|----------------------|
+| 1 | services/api/ | Node.js | Dockerfile |
+| 2 | services/worker/ | Python | Dockerfile |
+| 3 | services/gateway/ | Go | k8s manifest |
+
+Which service would you like to analyze? (number or name)
+
+Note: Each service gets its own `.gyre/` directory at its root.
+```
+
+**Rules:**
+- Do NOT attempt implicit boundary detection from directory naming conventions (e.g., don't assume `packages/` means services)
+- Only flag directories with BOTH a manifest AND deployment config
+- The selected service root becomes the analysis scope — all subsequent steps target that root
+- `.gyre/` directory is created at the selected service root, not the project root
+
+**If single service (or monorepo with shared deployment):**
+- Continue with the project root as analysis scope
+- `.gyre/` directory at project root
+
+## FINDINGS COMPILATION
+
+After all scans complete (and service root selected, if monorepo), compile findings into a structured summary for the user:
+
+```
+## Stack Detection Results
+
+| Category | Detected | Evidence |
+|----------|----------|----------|
+| Language/Framework | [e.g., Node.js / Next.js] | [e.g., package.json found] |
+| Container | [e.g., Docker + Compose] | [e.g., Dockerfile, docker-compose.yaml] |
+| Orchestration | [e.g., Kubernetes] | [e.g., k8s/ directory with manifests] |
+| CI/CD | [e.g., GitHub Actions] | [e.g., .github/workflows/] |
+| Observability | [e.g., OpenTelemetry + Prometheus] | [e.g., otel imports in deps] |
+| Cloud Provider | [e.g., AWS] | [e.g., terraform provider "aws"] |
+| Communication | [e.g., HTTP/REST + gRPC] | [e.g., express routes + .proto files] |
+
+**Not detected:** [list categories with no evidence found]
+```
+
+Present these findings to the user conversationally, explaining what was found and what wasn't.
+
+---
+
+## NEXT STEP
+
+Store scan results in working memory and proceed to:
+
+Load step: {project-root}/_bmad/bme/_gyre/workflows/stack-detection/steps/step-02-classify-stack.md