oh-my-agent-commandcode 0.0.0-stage → 20.38.3

package/skills/oma-observability/resources/vendor-categories.md

@@ -0,0 +1,352 @@
+---
+notes:
+  - "Example vendor lists are snapshots: verify via landscape.cncf.io before production selection"
+---
+
+# Observability Vendor Categories
+
+> as of 2026-Q2. No scheduled review is promised (see `SKILL.md` §Versioning & Deprecation); verify live status at https://landscape.cncf.io when load-bearing.
+
+## Preamble: Why Categories, Not a Registry
+
+This file is a **category taxonomy with timestamped example vendors**. It is not a vendor registry.
+
+**Why this distinction matters:**
+
+1. **Vendor names rot.** Examples from this codebase's own lifetime:
+   - Keptn: archived by CNCF, 2025-09
+   - Fluentd remains CNCF Graduated; the 2025-10 migration guide is not a deprecation announcement
+   - Pyroscope: was CNCF Sandbox; acquired by Grafana 2023; CNCF Sandbox status is uncertain post-acquisition (verify at landscape.cncf.io before citing)
+
+2. **Categories are stable.** "OSS full-stack", "SIEM", and "profiling specialist" have been coherent for years. The vendors filling them change.
+
+3. **No duplication with vendor-owned skills.** The following published skills already describe themselves authoritatively:
+   - `getsentry/sentry-sdk-setup`: Sentry SDK instrumentation
+   - `honeycombio/agent-skill`: Honeycomb OTel setup (8+ published skills)
+   - `Dash0 otel-instrumentation`: Dash0 OTel
+   - `Microsoft Azure Monitor exporters`: Azure-specific exporters
+   - `Datadog Labs dd-apm`: Datadog APM
+   Duplicating their content here creates drift, not value.
+
+4. **CNCF landscape is the authoritative live registry.** `landscape.cncf.io` tracks CNCF project status (Graduated / Incubating / Sandbox / Archived), vendor landscape, and category membership in real time. This file complements it with decision guidance; it does not copy or compete with it.
+
+## Timestamp Discipline
+
+All example vendor lists in this file are marked `as of 2026-Q2`.
+
+**Review triggers** (no scheduled cadence; see `SKILL.md` §Versioning & Deprecation): CNCF project status changes, acquisitions, deprecations, or new CNCF Graduated/Incubating entrants in covered categories.
+
+When reviewing:
+- Check CNCF project status changes at landscape.cncf.io
+- Check acquisition or archival announcements
+- Update the `as of YYYY-QX` markers on any changed sections
+
+---
+
+## Category Taxonomy
+
+### (a) OSS Full-Stack
+
+**Traits:** Self-hostable, covers metrics + logs + traces in one coherent stack, often includes UI, storage, and agents. No per-seat licensing. Operational burden is on the team.
+
+**Example vendors** (as of 2026-Q2):
+
+| Vendor | Metrics | Logs | Traces | Profiles | UI | Notes |
+|--------|---------|------|--------|----------|----|-------|
+| Grafana Labs LGTM+ | Mimir | Loki | Tempo | Pyroscope | Grafana | Alloy collector, Beyla eBPF auto-instr, Faro RUM, k6 load |
+| Elastic Stack (ELK) | Yes | Elasticsearch | APM | No | Kibana | Mature; storage costs at scale |
+| SigNoz | Yes | Yes | Yes | No | Yes | OTel-native from day 1; ClickHouse backend |
+| OpenObserve | Yes | Yes | Yes | No | Yes | Rust-based; lower storage footprint claim |
+
+**How to choose:**
+- Already using Grafana dashboards → Grafana LGTM+
+- Need full-text log search maturity → Elastic Stack
+- Want OTel-native with no legacy shim → SigNoz
+- Cost-sensitive storage + small team → OpenObserve or SigNoz
+
+**Delegation target:** For Grafana stack setup, invoke `oma-search --docs "Grafana LGTM+ OTel Collector setup"`. For Elastic, use Elastic documentation directly. No single vendor-owned skill covers the full OSS stack; delegate to `oma-search` unless a specific component skill is installed.
+
+---
+
+### (b) Commercial SaaS Unified APM
+
+**Traits:** Managed SaaS; covers metrics, logs, traces, and often RUM/synthetics/profiling in one product. Per-host or per-ingestion pricing. Reduced operational burden; vendor lock-in risk.
+
+**Example vendors** (as of 2026-Q2):
+
+| Vendor | Metrics | Logs | Traces | Profiles | RUM | Notes |
+|--------|---------|------|--------|----------|-----|-------|
+| Datadog | Yes | Yes | Yes | Yes | Yes | Broadest feature surface; highest cost at scale |
+| New Relic | Yes | Yes | Yes | Yes | Yes | Usage-based pricing; OTel-native ingest |
+| Dynatrace | Yes | Yes | Yes | Yes | Yes | AI-driven auto-discovery; OneAgent proprietary |
+| Sentry | Partial | Yes | Yes | No | Yes | Error-first; strong release tracking |
+| Grafana Cloud | Yes | Yes | Yes | Yes | Faro | Managed LGTM+; per-signal pricing |
+
+**How to choose:**
+- Maximum feature coverage, budget flexible → Datadog
+- OTel-native ingest preferred, usage pricing → New Relic
+- Auto-discovery in complex microservice env → Dynatrace
+- Error tracking + release correlation primary need → Sentry
+- Prefer OSS tools managed → Grafana Cloud
+
+**Delegation target:** `Datadog Labs dd-apm`, `getsentry/sentry-sdk-setup`. For New Relic / Dynatrace: `oma-search --docs "{vendor} OTel integration setup"`.
+
+---
+
+### (c) High-Cardinality Specialist
+
+**Traits:** Purpose-built for high-cardinality event-based observability. Avoids pre-aggregation. Enables arbitrary dimension slicing at query time. Dynamic sampling to control cost.
+
+**Example vendors** (as of 2026-Q2):
+
+| Vendor | Approach | Key features | Notes |
+|--------|----------|-------------|-------|
+| Honeycomb | Event-first, columnar | BubbleUp root-cause, dynamic sampling, Query Builder | OTel-native; no metrics tier (use separate tool) |
+
+**How to choose:**
+- Cardinality explosion on Prometheus/Datadog metrics → Honeycomb for traces/events
+- Need to slice by any arbitrary field post-hoc → Honeycomb
+- Metrics + high-cardinality in one product → pair Honeycomb with a TSDB (category i)
+
+**Delegation target:** `honeycombio/agent-skill` (8+ published skills for OTel setup, sampling config, and BubbleUp usage).
+
+---
+
+### (d) Profiling Specialist
+
+**Traits:** Continuous profiling (CPU, memory, goroutine, heap). Always-on, low-overhead. pprof or OTel profiling (OTEP 0239, currently alpha) as wire format. MELT+P fifth pillar.
+
+**Note on Pyroscope:** Originally CNCF Sandbox. Acquired by Grafana Labs in 2023. CNCF Sandbox status is uncertain post-acquisition; verify at landscape.cncf.io before citing CNCF affiliation.
+
+**Example vendors** (as of 2026-Q2):
+
+| Vendor | CNCF status | Backend | Notes |
+|--------|------------|---------|-------|
+| Parca | CNCF Sandbox | ClickHouse / S3 | OTEP 0239-aligned; open-source |
+| Grafana Pyroscope | See note above | Object storage | Integrated into Grafana LGTM+; formerly CNCF Sandbox |
+| Polar Signals Cloud | Commercial | Polar Signals | Enterprise managed Parca |
+
+**How to choose:**
+- Full OSS control → Parca
+- Already on Grafana LGTM+ → Grafana Pyroscope (co-located storage)
+- Managed + enterprise support → Polar Signals Cloud
+
+**Delegation target:** `oma-search --docs "Parca OTel profiling setup"` or `oma-search --docs "Grafana Pyroscope integration"`.
+
+---
+
+### (e) SIEM / Enterprise Logs
+
+**Traits:** Security information and event management. Compliance-grade log retention, correlation rules, threat detection, alerting. Often WORM / immutable storage. Targets SOC2 / ISO 27001 audit requirements.
+
+**Example vendors** (as of 2026-Q2):
+
+| Vendor | Log ingest | Threat detection | Compliance | Notes |
+|--------|-----------|-----------------|-----------|-------|
+| Splunk | Yes | Yes | Yes | Market leader; high licensing cost |
+| Elastic Security | Yes | Yes | Yes | Elastic Stack + SIEM rules; lower cost than Splunk |
+| Sumo Logic | Yes | Yes | Yes | Cloud-native; per-GB pricing |
+| Datadog Cloud SIEM | Yes | Yes | Partial | Add-on to Datadog unified APM |
+
+**How to choose:**
+- Enterprise compliance, existing Splunk investment → Splunk
+- Cost-sensitive, already on Elastic → Elastic Security
+- Cloud-native, no on-prem requirement → Sumo Logic
+- Already on Datadog, want unified → Datadog Cloud SIEM
+
+**Delegation target:** `oma-search --docs "{vendor} SIEM log pipeline setup"`. For audit-specific requirements see `signals/audit.md` in this skill.
+
+---
+
+### (f) FinOps / Cost Observability
+
+**Traits:** Kubernetes / cloud cost visibility, unit economics, per-tenant / per-namespace attribution. Cost is a first-class observability signal (D4 in design), not a boundary attribute. Distinct from APM cost-of-ownership analysis.
+
+**Example vendors** (as of 2026-Q2):
+
+| Vendor | CNCF status | K8s cost | Cloud cost | Notes |
+|--------|------------|---------|-----------|-------|
+| OpenCost | CNCF Incubating | Yes | AWS/GCP/Azure | Open spec + OSS implementation; Prometheus-native |
+| Kubecost | Commercial (OpenCost-based) | Yes | Yes | Adds multi-cluster, RBAC, Slack alerts |
+| CloudZero | Commercial SaaS | Partial | Yes | Business-unit cost allocation focus |
+
+**How to choose:**
+- OSS, Prometheus-integrated, per-namespace attribution → OpenCost
+- Multi-cluster + enterprise reporting → Kubecost
+- Cloud bill decomposed by product team → CloudZero
+
+**Delegation target:** `oma-search --docs "OpenCost Prometheus integration"`. For cost signal context see `signals/cost.md` in this skill.
+
+---
+
+### (g) Feature Flags / Progressive Delivery
+
+**Traits:** Controlled rollout of features to subsets of users or traffic. Release observability; correlate flag states with error rates and latency. GitOps-integrated progressive delivery.
+
+**Example vendors** (as of 2026-Q2):
+
+| Vendor | CNCF status | Flag eval | Progressive delivery | Notes |
+|--------|------------|---------|---------------------|-------|
+| OpenFeature | CNCF Incubating (2023-11-21) | Yes (SDK standard) | No | Standardizes flag SDK; vendor-agnostic |
+| Flagger | CNCF Graduated | No | Yes (canary/A-B/blue-green) | Prometheus/Datadog metric gating |
+| Argo Rollouts | N/A (Argo project) | No | Yes (canary/blue-green) | Kubernetes CRD; integrates with analysis templates |
+| LaunchDarkly | Commercial | Yes | Partial | Mature commercial flag platform |
+| Unleash | OSS + Commercial | Yes | No | Self-hostable flag platform |
+
+**How to choose:**
+- Standardize flag SDK across vendors → OpenFeature (pair with LaunchDarkly or Unleash as backend)
+- Automated canary promotion with metric gates → Flagger or Argo Rollouts
+- Per-tenant progressive rollout (feature flags) → LaunchDarkly or Unleash
+- GitOps-native canary on Kubernetes → Flagger (CNCF Graduated, Flux / Helm native)
+
+**Delegation target:** `oma-search --docs "OpenFeature SDK {runtime} setup"` or `oma-search --docs "Flagger canary analysis Prometheus"`. For release boundary observability see `boundaries/release.md` in this skill.
+
+---
+
+### (h) Log Pipeline / Collection
+
+**Traits:** High-throughput log and event collection, transformation, routing, and forwarding. Runs as DaemonSet agents (preferred) or standalone pipeline. OTel Collector is the 2026 standard for new deployments.
+
+**Fluentd note:** CNCF lists Fluentd as Graduated. Choose migration from workload requirements, resource use, and plugin support, not a deprecation claim. The CNCF 2025-10-01 migration guide states that Fluentd and Fluent Bit configuration syntax differs substantially; validate converted plugins/routes before cutover. Sources: <https://www.cncf.io/projects/fluentd/> and <https://www.cncf.io/blog/2025/10/01/fluentd-to-fluent-bit-a-migration-guide/>.
+
+**Example vendors** (as of 2026-Q2):
+
+| Vendor | CNCF status | Protocol support | Transform | Notes |
+|--------|------------|----------------|---------|-------|
+| Fluent Bit | CNCF Graduated | Multiple | Lua / built-in | Preferred Fluentd replacement; C, low memory |
+| OpenTelemetry Collector | CNCF Incubating | OTLP + many | processors | OTel-native; recommended for new deployments |
+| Vector (Datadog OSS) | Non-CNCF | Multiple | VRL | Rust; high throughput; Datadog-backed |
+| Cribl Stream | Commercial | Multiple | Yes | Enterprise routing + data shaping |
+
+**How to choose:**
+- Migrating from Fluentd → compare Fluent Bit plugin/route support; convert configuration and validate in parallel (not a drop-in config replacement)
+- New OTel-native deployment → OpenTelemetry Collector
+- High-throughput with Rust reliability → Vector
+- Enterprise data routing with UI + compliance → Cribl Stream
+
+**Delegation target:** `oma-search --docs "Fluent Bit Kubernetes DaemonSet setup"` or `oma-search --docs "OTel Collector configuration {backend}"`. For collector topology guidance see `transport/collector-topology.md` in this skill.
+
+---
+
+### (i) Time Series Storage / Long-term Metrics
+
+**Traits:** Purpose-built for metrics storage at scale. Prometheus-compatible query (PromQL). Long-term retention beyond Prometheus 15-day default. HA + multi-tenancy for production.
+
+**Example vendors** (as of 2026-Q2):
+
+| Vendor | CNCF status | Multi-tenant | Object storage | Notes |
+|--------|------------|------------|---------------|-------|
+| Prometheus | CNCF Graduated | No (single-tenant) | No | Standard scrape source; 15d retention default |
+| Thanos | CNCF Incubating (2020-08-19) | Yes | Yes (S3/GCS/Azure) | Sidecar or receive mode; global query view |
+| Cortex | CNCF Incubating | Yes | Yes | Horizontally scalable; more complex ops |
+| Grafana Mimir | Non-CNCF (Grafana OSS) | Yes | Yes | Evolved from Cortex; simpler ops |
+| VictoriaMetrics | Non-CNCF (OSS + Commercial) | Cluster edition | Yes | High compression; low resource usage |
+| InfluxDB | Non-CNCF (Commercial OSS) | Yes (Cloud) | Yes | Line protocol; IOx rewrite in Rust |
+
+**How to choose:**
+- Starting fresh, Kubernetes, team familiar with Grafana → Grafana Mimir
+- Need CNCF Graduated status for procurement → verify an eligible project with CNCF; Thanos is Incubating and does not meet a Graduated-only requirement
+- Multi-tenant with complex federation needs → Cortex
+- Resource-constrained or high compression priority → VictoriaMetrics
+- Time-series with SQL query surface needed → InfluxDB IOx
+
+**Delegation target:** `oma-search --docs "Thanos sidecar Prometheus setup"` or `oma-search --docs "Grafana Mimir distributed mode"`.
+
+---
+
+### (j) Crash Analytics (Mobile-Heavy)
+
+**Traits:** Symbolication of native crash stacks. Crash-free rate (CFR) tracking. Release-correlated crash trends. ANR (Application Not Responding) detection. Mobile session replay context.
+
+**Example vendors** (as of 2026-Q2):
+
+| Vendor | iOS | Android | Web | Notes |
+|--------|-----|---------|-----|-------|
+| Firebase Crashlytics | Yes | Yes | No | Free; Google ecosystem; dSYM auto-upload |
+| Sentry | Yes | Yes | Yes | Cross-platform; OTel trace correlation |
+| Bugsnag | Yes | Yes | Yes | Strong breadcrumb API; Smartisan noise reduction |
+| Embrace | Yes | Yes | No | Mobile-first; session replay; network body capture |
+| Datadog Error Tracking | Yes | Yes | Yes | Unified with Datadog APM |
+
+**How to choose:**
+- Mobile-only, budget zero → Firebase Crashlytics
+- Cross-platform (mobile + web + backend) correlation → Sentry
+- Mobile session replay + user journey → Embrace
+- Already on Datadog APM → Datadog Error Tracking
+- Need noise reduction + grouping quality → Bugsnag
+
+**Delegation target:** `getsentry/sentry-sdk-setup` for Sentry. For others: `oma-search --docs "{vendor} iOS/Android crash reporting setup"`. For crash analytics context see `layers/L7-application/crash-analytics.md` in this skill.
+
+---
+
+## Intent to Category Routing
+
+| User intent | Primary categories | Notes |
+|------------|-------------------|-------|
+| Setup full-stack OSS monitoring | (a) OSS Full-Stack, (h) Log Pipeline, (i) TSDB, (d) Profiling | Start with (a); (h)+(i)+(d) fill gaps |
+| Setup commercial managed APM | (b) Commercial SaaS Unified APM | Select vendor by criteria in (b) |
+| Migrate off Fluentd | (h) Log Pipeline | Fluent Bit preferred (CNCF 2025-10 guide); OTel Collector for OTel-native |
+| High-cardinality trace investigation | (c) High-Cardinality Specialist | Honeycomb + dynamic sampling |
+| FinOps cost attribution program | (f) FinOps / Cost Observability | OpenCost + `signals/cost.md` |
+| Per-tenant progressive rollout | (g) Feature Flags / Progressive Delivery | OpenFeature SDK + Flagger or Argo Rollouts |
+| Mobile crash rate SLO | (j) Crash Analytics | Pair with (b) or (a) for backend traces |
+| Long-term metric retention | (i) TSDB | Thanos or Mimir on top of Prometheus |
+| Continuous profiling (MELT+P) | (d) Profiling Specialist | Parca (OSS) or Pyroscope (Grafana) |
+| SIEM / SOC2 audit log compliance | (e) SIEM / Enterprise Logs | See `signals/audit.md` for WORM requirements |
+
+---
+
+## How to Delegate
+
+### When a vendor-specific skill is installed
+
+Invoke the skill directly:
+
+| Skill | Coverage |
+|-------|---------|
+| `getsentry/sentry-sdk-setup` | Sentry SDK instrumentation, error tracking, release tracking |
+| `honeycombio/agent-skill` | Honeycomb OTel setup, BubbleUp, dynamic sampling (8+ published skills) |
+| `Dash0 otel-instrumentation` | Dash0 OTel generic instrumentation |
+| `Microsoft Azure Monitor exporters` | Azure-specific OTel exporters and Monitor integration |
+| `Datadog Labs dd-apm` | Datadog APM, log correlation, distributed tracing |
+
+### When no vendor-specific skill is installed
+
+Route to search with vendor + observability context:
+
+```
+oma-search --docs "{vendor} observability setup"
+oma-search --docs "{vendor} OTel integration {runtime}"
+oma-search --docs "{vendor} {signal} configuration"
+```
+
+Examples:
+- `oma-search --docs "Grafana Mimir Prometheus remote_write setup"`
+- `oma-search --docs "OpenCost Kubernetes namespace cost attribution"`
+- `oma-search --docs "Fluent Bit Kubernetes DaemonSet migration from Fluentd"`
+- `oma-search --docs "Parca continuous profiling Go gRPC"`
+
+### CNCF landscape as canonical vendor source
+
+For questions about current CNCF project status, vendor landscape membership, or whether a project is still maintained:
+
+```
+oma-search --docs "site:landscape.cncf.io {category or vendor}"
+```
+
+Or navigate directly to https://landscape.cncf.io; it is the authoritative live registry. This file does not attempt to replicate it.
+
+---
+
+## Footer
+
+**Timestamp:** as of 2026-Q2
+
+**Review triggers** (no scheduled cadence): CNCF project status changes, acquisitions, deprecations, or new CNCF Graduated/Incubating entrants in covered categories.
+
+**Authoritative live source:** https://landscape.cncf.io
+
+**Known pending verifications (as of 2026-Q2):**
+- Pyroscope CNCF status post-Grafana acquisition (2023): check landscape.cncf.io before citing CNCF affiliation
+- Thanos: Incubating since 2020-08-19; <https://www.cncf.io/projects/thanos/> (checked 2026-10-04)
+- OpenFeature: Incubating since 2023-11-21; <https://www.cncf.io/projects/openfeature/> (checked 2026-10-04)

package/skills/oma-orchestration/SKILL.md

@@ -0,0 +1,302 @@
+---
+name: oma-orchestration
+description: Dispatch and supervise parallel specialist agents with durable task
+  state. Use when automated multi-agent execution is requested.
+---
+
+# Orchestration - Automated Multi-Agent Coordination
+
+## Scheduling
+
+### Goal
+Automatically orchestrate multi-agent execution with task decomposition, native/fallback dispatch, memory coordination, progress monitoring, verification, QA cross-review, retry, and result collection.
+
+### Intent signature
+- User asks to orchestrate, run in parallel, automate multi-agent execution, or coordinate full-stack work end to end.
+- Task requires multiple specialist agents and a persistent review/remediation loop.
+
+### When to use
+- Complex feature requires multiple specialized agents working in parallel
+- User wants automated execution without manually spawning agents
+- Full-stack implementation spanning backend, frontend, mobile, and QA
+- User says "run it automatically", "run in parallel", or similar automation requests
+
+### When NOT to use
+- Simple single-domain task -> use the specific agent directly
+- User wants step-by-step manual control -> use oma-coordination
+- Quick bug fixes or minor changes
+
+### Expected inputs
+- Complex feature or workflow request
+- Project config, model/vendor routing, agent types, task constraints, and workspace/session needs
+- Acceptance criteria and verification expectations
+
+### Expected outputs
+- Orchestrator session state, task board, progress files, result files, and final summary
+- Specialist agent outputs after mechanical checks, automated verify, and QA cross-review
+- Review history and retry/remediation status when loops fail
+
+### Dependencies
+- `.agents/oma-config.yaml`, `.codex/agents/*.toml`, `.gemini/agents/*.md`, or fallback `oma agent spawn`
+- Memory provider config, subagent prompt template, scripts, task templates, verify script, and session metrics
+
+### Control-flow features
+- Branches by vendor/native dispatch availability, priority tiers, agent completion/failure, verification status, QA verdict, retry limits, and unresolved decisions
+- Spawns processes/agents and reads/writes memory/result files
+- Preserves unresolved evidence when bounded recovery stops
+
+## Structural Flow
+
+### Entry
+1. Resolve agent vendor routing and runtime dispatch path.
+2. Decompose request into priority-tiered tasks.
+3. For each task, classify into one or more `domain_tags` by matching against the `Intent signature` block of each installed `.agents/skills/oma-*/SKILL.md`. Tasks that match no domain confidently inherit the union of their parent feature's tags.
+4. Select the references needed by each task. One confidently matched skill is sufficient; expand the set when classification is uncertain or a dependency requires another domain.
+5. Record selected domains, references, and any fallback reason in the task board. These are coordinator notes, not launcher-enforced exposure fields; use only reference/context controls supported by the active dispatch path.
+6. Apply the shared collaboration policy before dispatch: assign edit ownership, peer contact paths, and a collection owner.
+
+### Scenes
+1. **PREPARE**: Plan, setup session ID, and initialize memory files.
+2. **ACT**: Spawn agents by priority tier within parallelism limits.
+3. **VERIFY**: Run self-check, `oma verify`, and QA cross-review loop.
+4. **RECOVER**: Retry failed agents with review history when limits allow.
+5. **FINALIZE**: Collect verified claims, compile summary, and preserve progress artifacts.
+
+### Transitions
+- If native dispatch is available for current runtime/vendor, use it.
+- If vendors differ or native path is unavailable, use fallback spawn.
+- If verify or QA fails, feed feedback back to the implementation agent.
+- If recovery limits are exceeded, preserve review history and return `partial` or `failed`; never force completion.
+- If recovery shows that a required domain reference was missing, update the task's reference selection without changing its frozen acceptance contract, and supply it through the supported context mechanism.
+
+### Failure and recovery
+- Retry failed agents up to configured limits.
+- Re-spawn with review history when review loop is exhausted.
+- Continue independent work after recording material corrections; ask only for a material missing decision.
+
+### Exit
+- Success: all tasks complete, verify/review pass, and results are summarized.
+- Partial success: failed agents, exhausted review loops, or missing verification are explicit.
+
+## Logical Operations
+
+### Actions
+| Action | SSL primitive | Evidence |
+|--------|---------------|----------|
+| Read config and task context | `READ` | oma config, routing, request |
+| Classify task into domain tags | `INFER` | task text vs each skill's `Intent signature` |
+| Select task references | `SELECT` | confident domain matches, dependencies, and supported context controls |
+| Select dispatch path | `SELECT` | Native vs fallback |
+| Write session state | `WRITE` | task board and memory files |
+| Spawn agents | `CALL_TOOL` | exposed native role-subagent tool or `oma agent spawn` |
+| Poll progress | `READ` | progress/result files |
+| Run verification | `CALL_TOOL` | `oma verify`, tests, QA |
+| Update retry state | `UPDATE_STATE` | loop counters and CD metrics |
+| Report final result | `NOTIFY` | compiled summary |
+
+### Tools and instruments
+- Exposed native role-subagent tools, fallback spawn scripts, memory tools, verify script, QA agent
+- Session metrics, prompt templates, task templates
+
+### Canonical command path
+```bash
+oma agent spawn <agent-type> <prompt-file> <session-id> --task-id <task.id> -w <workspace>
+oma verify agent <agent-type> --workspace <workspace> --json
+```
+
+When native runtime dispatch is available, prefer the runtime-specific native path listed in this skill before falling back to `oma agent spawn`.
+
+### Resource scope
+| Scope | Resource target |
+|-------|-----------------|
+| `LOCAL_FS` | Session, task-board, progress, result, config files |
+| `PROCESS` | Agent CLI processes and verify scripts |
+| `MEMORY` | Session state and unresolved decisions |
+| `CODEBASE` | Workspaces owned by spawned agents |
+
+### Preconditions
+- Task is decomposable into specialist agent work.
+- Runtime/vendor dispatch path or fallback exists.
+
+### Effects and side effects
+- Spawns agents and writes session/progress/result artifacts.
+- May cause code changes through specialist agents.
+- May trigger iterative review and retries.
+
+### Guardrails
+1. Orchestrate per-agent dispatch from the project configuration before spawning any agent.
+2. If `target_vendor === current_runtime_vendor` and the runtime has a verified native path, use native dispatch.
+3. Otherwise fall back to `oma agent spawn`.
+4. Never exceed configured parallelism or the aggregate recovery budget. Ordinary retries and exploration hypotheses both consume it.
+5. Keep session state, task-board state, progress files, claims, and receipts aligned. Use the plan task ID on every spawn and native begin/finish path.
+6. Select references by task needs and confidence. Do not expand to all skills solely because one skill matches, or assume task-board metadata enforces runtime exposure.
+
+Current native executor paths:
+- Claude Code: Agent tool with `.claude/agents/{agent}.md` definitions (multiple Agent tool calls in one message run in parallel; results return synchronously — no polling)
+- OpenCode / Kilo Code: native `task` tool with `subagent_type: {agent-id}`; do not use `oma agent spawn` for same-session OpenCode or Kilo work because it will not appear as a native child task
+- Codex: use the current session's exposed native subagent tool with the resolved custom role from `.codex/agents/*.toml` when supported; otherwise use `oma agent spawn`. Model tiering follows `../_shared/core/vendor-detection.md`.
+- Gemini: use the current session's exposed native role-subagent tool with the resolved role when supported; otherwise use `oma agent spawn`.
+
+`codex exec` and `gemini -p` start external CLI sessions. An `@agent` string in a prompt does not establish native dispatch or apply a custom-role contract.
+
+### Configuration
+
+| Setting | Default | Description |
+|---------|---------|-------------|
+| MAX_PARALLEL | 3 | Max concurrent subagents |
+| MAX_RECOVERY_ATTEMPTS | 3 | Total retries and exploration hypotheses per task, including the original attempt |
+| POLL_INTERVAL | bounded backoff | Fallback only when completion notifications are unavailable |
+| Turn guidance | role-specific | Checkpoint/resume signal, not a hard stop or approval boundary |
+
+These are workflow defaults. Resolve model/vendor, parallelism, and budget settings from project configuration. `config/cli-config.yaml` supplies the vendor transport registry; it does not select the active vendor or override runtime execution settings.
+
+### Memory Configuration
+
+Memory provider and tool names are configurable via `.agents/mcp.json` (not the repo-root `.mcp.json`, which is the Claude Code MCP server config):
+```json
+{
+  "memoryConfig": {
+    "provider": "file",
+    "basePath": ".agents/state/memories",
+    "tools": {
+      "read": "Read",
+      "write": "Write",
+      "edit": "Edit"
+    }
+  }
+}
+```
+
+### Workflow Phases
+
+**PHASE 1 - Plan**: Reuse the current valid plan or decompose the request; preserve injected session/task/run IDs.
+**PHASE 1.5 - References**: Select task references as described in Entry; record uncertainty and expansion reasons without assuming runtime enforcement.
+**PHASE 2 - Setup**: Create session/task-board artifacts with the current IDs and selected references.
+**PHASE 3 - Execute**: Dispatch ready tasks within MAX_PARALLEL using supported native or fallback context controls.
+**PHASE 4 - Monitor**: Prefer completion notifications; otherwise use one coordinator with bounded polling backoff. Follow `../_shared/core/execution-policy.md` for the shared deadline, cancellation, resource ownership, and shutdown rules. Cancellation or deadline exhaustion stops dispatch and recovery before verification.
+**PHASE 4.5 - Verify**: Run mechanical checks for every completed agent; run `oma verify agent {agent-type}` only for `backend`, `frontend`, `mobile`, `qa`, `debug`, and `pm`; then run QA cross-review for every completed implementation
+**PHASE 5 - Collect**: Read claims and run-scoped reports for plan tasks whose checks passed; compile summary without deleting evidence.
+
+### Memory File Ownership
+
+| File | Owner | Others |
+|------|-------|--------|
+| `orchestrator-session-{sessionId}.md` | orchestrator | read-only |
+| `task-board-{sessionId}.md` | orchestrator | read-only |
+| `progress-{agentId}-{taskId}-{runId}-{sessionId}.md` | that run | orchestrator reads |
+| `result-{agentId}-{taskId}-{runId}-{sessionId}.md` | that run | orchestrator reads |
+
+### Agent-to-Agent Review Loop (PHASE 4.5)
+
+After each agent completes, enter an iterative review loop, not a single-pass verification.
+
+### Loop Flow
+
+```
+Agent completes work
+    ↓
+[1] Mechanical Self-Check: lint, type-check, tests, diff scope
+    ↓
+[2] Verify: For supported types, run `oma verify agent {agent-type} --workspace {workspace}`
+    Unsupported (`db`, `refactor`, `architecture`, `tf-infra`, `docs`) → record SKIP and continue
+    ↓ FAIL → Agent receives feedback, fixes, back to [1]
+    ↓ PASS
+[3] Cross-Review: QA agent reviews the changes
+    ↓ FAIL → Agent receives review feedback, fixes, back to [1]
+    ↓ PASS
+Accept result
+```
+
+### Step Details
+
+**[1] Mechanical Self-Check** (formerly "Self-Review"):
+Before requesting external review, the implementation agent must:
+- Run lint, type-check, and tests in the workspace
+- Verify only planned files were modified (diff scope check)
+- Fix any mechanical failures (compile errors, test failures)
+
+**Quality judgment is NOT performed in this step.**
+Design quality, architecture alignment, and acceptance criteria satisfaction
+are evaluated exclusively in [3] Cross-Review by the QA agent.
+Reason: Self-evaluation bias causes agents to consistently overrate their own output
+(ref: Anthropic harness design research).
+
+**[2] Automated Verify**:
+```bash
+oma verify agent {agent-type} --workspace {workspace} --json
+```
+- Run only for `backend`, `frontend`, `mobile`, `qa`, `debug`, and `pm`.
+- For `db`, `refactor`, `architecture`, `tf-infra`, and `docs`, record that automated verify is unsupported and continue to QA cross-review after the mechanical checks.
+- **PASS (exit 0)**: Proceed to cross-review
+- **FAIL (exit 1)**: Feed verify output back to the agent as correction context
+
+**[3] Cross-Review**: Spawn QA agent to review the changes:
+- QA agent reads the diff, runs checks, evaluates against acceptance criteria
+<!-- oma-docs:ignore-start -->
+- If `docs/CODE-REVIEW.md` exists, QA agent uses it as the review checklist
+<!-- oma-docs:ignore-end -->
+- QA agent outputs: PASS (with optional nits) or FAIL (with specific issues)
+- On FAIL: issues are fed back to the implementation agent for fixing
+
+### Loop Limits
+
+| Counter | Max | On Exceeded |
+|---------|-----|-------------|
+| Self-check + fix cycles | 3 | Escalate to cross-review regardless |
+| Cross-review rejections | 2 | Report to user with review history |
+| Total loop iterations | 5 | Stop recovery; preserve failed checks and return `partial` or `failed` |
+
+### Review Feedback Format
+
+When feeding review results back to the implementation agent:
+```
+## Review Feedback (iteration {n}/{max})
+**Reviewer**: {self / verify / qa-agent}
+**Verdict**: FAIL
+**Issues**:
+1. {specific issue with file and line reference}
+2. {specific issue}
+**Fix instruction**: {what to change}
+```
+
+This replaces single-pass verification. Most "nitpicking" should happen agent-to-agent.
+Resolve relevant automated checks before handoff. Ask for approval only when the next action is outside existing authorization.
+
+### Recovery Budget (after review loop exhaustion)
+
+Maintain one budget per workflow lineage and logical goal: `attempts_used`, `attempts_remaining`, and any
+configured cost cap. The original attempt, each ordinary retry, and each
+exploration hypothesis consume one attempt. Before starting recovery, reserve
+the complete next action; do not exceed the budget or start an incomplete
+exploration round.
+
+Use the plan's stable `lineage_id` and task `goal_id` from `../_shared/runtime/result-contract.md`. New task/run/session IDs do not reset that budget. Freeze the full JSON plan at first dispatch; reject recursive planning/review tasks and post-dispatch plan revisions. A contract change requires an explicitly separated new session and lineage.
+
+Classify failures before retrying: `PRODUCT_FAILURE` follows the remaining product recovery budget; `WORKFLOW_EVIDENCE_FAILURE` means current product checks passed but completion claims or bindings failed. Automatic resume stops evidence-only replay. Allow at most one metadata-only repair under the existing task and frozen plan, consuming the same budget, then stop with a partial handoff if unresolved. Do not create PM tasks, rerun product planning, or import another workflow's plan-review loop for evidence failures.
+
+- First remaining attempt: re-spawn with review history.
+- Later attempts: choose either one different retry or a 2–3 hypothesis round
+  only if enough attempts and cost remain.
+- On cap exhaustion, preserve all checks, review findings, and unresolved work.
+  The task is `partial` or `failed`, never `completed`.
+
+### Session evidence
+
+For material corrections or review findings, retain the cause, impact, and evidence in existing task artifacts. Use `../_shared/core/session-metrics.md` when a retrospective or separate session summary is useful. Do not score clarification questions or require an RCA based on counters. Resolve the affected work and ask only for a material missing decision.
+
+## References
+- Parallel worker collaboration: `../_shared/core/collaboration-policy.md` (before assigning parallel work or coordinating peer issues, ownership handoffs, and result collection)
+- Prompt template: `resources/subagent-prompt-template.md`
+- Memory schema: `resources/memory-schema.md`
+- Scripts: `scripts/spawn-agent.sh`, `scripts/parallel-run.sh`, `scripts/verify.sh`
+- Task templates: `templates/`
+- Skill-to-agent mapping: `../_shared/core/skill-routing.md`
+- Verification: `scripts/verify.sh <agent-type>`
+- Session metrics: `../_shared/core/session-metrics.md`
+- API contract template (SSOT): `../_shared/core/api-contracts/template.md`; read generated contracts from `.agents/results/api-contracts/` (run artifact) or `docs/plans/contracts/` (durable spec)
+- Context loading: `../_shared/core/context-loading.md`
+- Task decomposition: `../_shared/core/difficulty-guide.md` (unresolved scope or dependencies)
+- Clarification protocol: `../_shared/core/clarification-protocol.md`
+- Context budget: `../_shared/core/context-budget.md`
+- Code intelligence: `../_shared/core/code-intelligence.md`
+- Runtime lessons: `../_shared/core/lessons-learned.md` (recurring failure or requested retrospective)