feat(qyl-instrumentation): Teams API orchestration + competition polish (#149)

* docs: add spec-0002 qyl Claude Code observability

Comprehensive spec for building Claude Code session observability
into qyl's AI telemetry dashboard. Zero-instrumentation approach
using Claude Code's native OTLP telemetry export (4 env vars).

Covers: OTLP data flow, DuckDB schema, 5 API endpoints, React
hooks, 4 dashboard components, SSE live streaming, and 4-phase
implementation plan. Correlation via prompt.id across all events.

Also fixes CLAUDE.md skill count (6 → 4 after council/invoke and
feature-dev/code-review skill deletions).

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat(qyl-instrumentation): rebuild as Teams API orchestration (v2.0.0)

Restructure from 3 standalone agents to 1 Opus captain + 4 Sonnet specialists.
Captain pre-reads otelwiki bundled semconv docs before spawning specialists —
eliminates runtime web search/fetch. New /observe command implements full
TeamCreate → spawn → cross-pollinate → synthesize → TeamDelete lifecycle.

New: opus-captain agent, qyl-platform-specialist agent, /observe command.
Changed: removed WebSearch/WebFetch from all specialist tools, added Team Protocol
sections with SendMessage coordination patterns.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

* feat(qyl-instrumentation): competition-ready polish (v2.1.0)

Add hero scenario (proactive secretary), 8-layer trace example,
attribute decision tree, multi-turn agent traces, GenAI failure
modes, TypeSpec-to-dashboard flow, MCP/SSE patterns, SEMCONV_CONTEXT
shape, verification checklists, and example run walkthrough across
all 6 agent/command files. All stay under 250 lines.

Co-Authored-By: Claude Opus 4.6 <noreply@anthropic.com>

---------

Co-authored-by: Claude Opus 4.6 <noreply@anthropic.com>

Author: ANcpLua

.claude-plugin/marketplace.json

@@ -5,7 +5,7 @@
     "url": "https://github.com/ANcpLua"
   },
   "metadata": {
-    "description": "Claude Code plugin marketplace: 8 plugins, 23 commands, 4 skills, 14 agents. Multi-agent orchestration, cognitive amplification, OpenTelemetry docs, and .NET build enforcement."
+    "description": "Claude Code plugin marketplace: 9 plugins, 24 commands, 4 skills, 19 agents. Multi-agent orchestration, cognitive amplification, OpenTelemetry docs, .NET build enforcement, and compile-time instrumentation."
   },
   "plugins": [
     {
@@ -55,6 +55,12 @@
       "description": "Multi-agent workflow orchestration (9 commands + 2 skills: eight-gates, hades): fix, turbo-fix, fix-pipeline, tournament, mega-swarm, deep-think, batch-implement, red-blue-review, baryon-mode. Hades, eight-gates, and red-blue-review use Teams API for reactive collaboration.",
       "version": "2.1.0",
       "source": "./plugins/exodia"
+    },
+    {
+      "name": "qyl-instrumentation",
+      "description": "Teams API observability orchestration for qyl: 1 Opus captain + 4 Sonnet specialists. Captain pre-reads otelwiki semconv docs, dispatches servicedefaults, collector, genai, and platform specialists. Zero runtime web search.",
+      "version": "2.1.0",
+      "source": "./plugins/qyl-instrumentation"
     }
   ]
 }

CHANGELOG.md

@@ -12,6 +12,24 @@ and the project follows [Semantic Versioning](https://semver.org/spec/v2.0.0.htm
 
 ### Changed
 
+- **`qyl-instrumentation` (2.0.0 → 2.1.0)**: Competition-ready polish for all 6 agent/command files. Added hero scenario (proactive secretary notification handler), 8-layer trace example, attribute decision tree, performance profile, multi-turn agent trace, GenAI failure modes with 15-second async window, TypeSpec-to-dashboard end-to-end flow, MCP tool pattern, SSE consumption pattern, SEMCONV_CONTEXT shape, spawn/synthesis verification checklists, and example run walkthrough. All files stay under 250 lines
+
+### Added
+
+- **`docs/specs/spec-0002-qyl-claude-code-observability.md`**: Comprehensive spec for building Claude Code session observability into qyl's AI telemetry dashboard. Covers OTLP data flow (native `claude_code.*` metrics + events), DuckDB schema, 5 API endpoints, React hooks, 4 dashboard components, SSE live streaming, and 4-phase implementation plan. Zero-instrumentation approach — uses Claude Code's built-in OTLP telemetry export via 4 env vars
+- **`qyl-instrumentation/commands/observe.md`**: Teams API orchestration command — Opus captain pre-reads otelwiki bundled semconv docs, assembles SEMCONV_CONTEXT + SHARED_AWARENESS, spawns 4 Sonnet specialists in parallel, coordinates cross-pollination via SendMessage, synthesizes. Zero runtime web search
+- **`qyl-instrumentation/agents/opus-captain.md`**: Opus captain agent — orchestrates context assembly and team coordination, reads otelwiki docs before any specialist spawns
+- **`qyl-instrumentation/agents/qyl-platform-specialist.md`**: 4th Sonnet specialist covering MCP server, React dashboard, browser OTLP SDK, SSE streaming, and Copilot extensibility
+
+### Changed
+
+- **`qyl-instrumentation`**: Rebuilt from 3 standalone agents (v1.0.0) to Teams API orchestration (v2.0.0). 1 Opus captain + 4 Sonnet specialists. Captain pre-reads otelwiki bundled docs — specialists receive pre-assembled semconv context in spawn prompts instead of web searching at runtime
+- **`qyl-instrumentation` agents**: Removed `WebSearch` and `WebFetch` from all 3 existing specialist tool lists. Added Team Protocol sections documenting SendMessage coordination patterns and SEMCONV_CONTEXT injection
+- **`qyl-instrumentation/agents/otel-genai-architect.md`**: Convention verification now references captain's SEMCONV_CONTEXT instead of WebSearch
+- **`marketplace.json`**: Updated qyl-instrumentation description and version (1.0.0 → 2.0.0), agent count 17 → 19, command count 23 → 24
+
+### Changed
+
 - **`exodia/skills/hades`**: Migrated from vague Teams references to explicit Teams API. SKILL.md now uses `TeamCreate`, `TeamDelete`, `SendMessage` (shutdown_request/shutdown_response), `TaskCreate`/`TaskList`/`TaskUpdate` with explicit parameters. Removed fallback subagent path and duplicate STEP -1 block. All 4 teammate templates (auditors, eliminators, verifiers, goggles) updated: vague `MESSAGE` → `SendMessage (recipient: "...")`, vague task list → `TaskCreate`/`TaskUpdate`, team context preamble and shutdown protocol added
 - **`exodia/eight-gates` Gate 7 EXECUTE**: Removed dual Mode A (Task subagents) / Mode B (Agent Teams) pattern. Teams API is now the single execution mode. Lane workers coordinate via `SendMessage` and claim work via `TaskCreate`/`TaskUpdate`. Collision avoidance uses teammate messaging
 - **`exodia/skills/hades` allowed-tools**: Added `TeamCreate`, `TeamDelete`, `TaskCreate`, `TaskList`, `TaskUpdate`, `SendMessage` to frontmatter

plugins/qyl-instrumentation/.claude-plugin/plugin.json

@@ -0,0 +1,20 @@
+{
+  "name": "qyl-instrumentation",
+  "version": "2.1.0",
+  "description": "Teams API observability orchestration for qyl: 1 Opus captain pre-reads otelwiki semconv docs, dispatches 4 Sonnet specialists (servicedefaults, collector, genai, platform) via /observe command. Zero runtime web search.",
+  "author": {
+    "name": "ANcpLua",
+    "email": ""
+  },
+  "repository": "https://github.com/ANcpLua/ancplua-claude-plugins",
+  "license": "MIT",
+  "keywords": [
+    "qyl",
+    "observability",
+    "opentelemetry",
+    "teams-api",
+    "instrumentation",
+    "genai"
+  ],
+  "commands": "./commands"
+}

plugins/qyl-instrumentation/README.md

@@ -0,0 +1,87 @@
+# qyl-instrumentation
+
+Teams API observability orchestration for qyl's compile-time OTel instrumentation system.
+
+## Architecture
+
+```text
+/qyl-instrumentation:observe [task]
+        │
+        v
+  captain (Opus) ── pre-reads otelwiki bundled semconv docs
+        │              assembles SEMCONV_CONTEXT + SHARED_AWARENESS
+        │
+        ├── servicedefaults (Sonnet) ── compile-time attributes, generators
+        ├── collector (Sonnet) ──────── OTLP ingestion, DuckDB, API, TypeSpec
+        ├── genai (Sonnet) ──────────── GenAI semconv, agent/LLM tracing
+        └── platform (Sonnet) ───────── MCP server, dashboard, browser SDK
+              │                │               │                │
+              └────────────────┴───────────────┴────────────────┘
+                          cross-pollinate via SendMessage
+```
+
+## Key Innovation
+
+**Zero runtime web search.** The Opus captain pre-reads otelwiki's bundled semantic
+convention docs BEFORE spawning specialists. Each Sonnet specialist receives
+pre-assembled semconv context in their spawn prompt — they never need to web search
+or web fetch.
+
+This means:
+
+- Specialists work with VERIFIED, CURRENT attribute data (from otelwiki's synced docs)
+- No runtime latency from web searches
+- No hallucinated attribute names from stale training data
+- Captain verifies doc freshness — warns if otelwiki needs sync
+
+## What This Plugin Provides
+
+### Command
+
+| Command | Purpose |
+|---------|---------|
+| `/qyl-instrumentation:observe` | Full team orchestration — context assembly, spawn, coordinate, synthesize |
+
+### Agents
+
+| Agent | subagent_type | Model | Domain |
+|-------|---------------|-------|--------|
+| Opus Captain | `opus-captain` | Opus 4.6 | Orchestration, context assembly |
+| ServiceDefaults Specialist | `servicedefaults-specialist` | Sonnet 4.6 | Source generator, attribute vocabulary, interceptor pipelines |
+| qyl Observability Specialist | `qyl-observability-specialist` | Sonnet 4.6 | OTLP ingestion, DuckDB, collector architecture, TypeSpec schemas |
+| OTel GenAI Architect | `otel-genai-architect` | Sonnet 4.6 | GenAI semantic conventions, agent tracing, LLM telemetry |
+| qyl Platform Specialist | `qyl-platform-specialist` | Sonnet 4.6 | MCP server, dashboard, browser SDK, SSE streaming |
+
+## Usage
+
+Full team orchestration:
+
+```text
+/qyl-instrumentation:observe Add tracing to the new OrderService with GenAI telemetry
+/qyl-instrumentation:observe Design DuckDB schema for agent invocation metrics
+/qyl-instrumentation:observe Instrument the MCP server with request/response tracing
+```
+
+Individual specialist (bypasses team, no pre-fetched context):
+
+```text
+Task(subagent_type="qyl-instrumentation:servicedefaults-specialist", prompt="Add [Traced] to PaymentService")
+Task(subagent_type="qyl-instrumentation:otel-genai-architect", prompt="Validate GenAI attributes against semconv")
+```
+
+## Shared Awareness
+
+All agents are aware of:
+
+- **AI monitoring use cases:** silent failures, malformed responses, performance
+  bottlenecks, agent loops, cost attribution, context overflow, tool failures,
+  safety violations
+- **Quality criteria:** accuracy (20-25%), reasoning (20-25%), creativity (15%),
+  UX (15%), reliability/safety (20%)
+- **Enterprise integration:** External MCP (8pts), Connected Agents Architecture
+  (15pts), OAuth (5pts), Adaptive Cards (5pts)
+
+## Dependencies
+
+- **otelwiki plugin** — captain reads bundled docs for semconv context (graceful degradation if missing)
+- **ancplua-project-routing** — detects qyl workspace and injects agent types into session

plugins/qyl-instrumentation/agents/opus-captain.md

@@ -0,0 +1,86 @@
+---
+name: opus-captain
+description: >-
+  qyl observability captain. Pre-reads otelwiki bundled semconv docs, creates team,
+  dispatches 4 Sonnet specialists with pre-assembled context, coordinates cross-pollination,
+  synthesizes final output. Uses claude-opus-4-6.
+model: claude-opus-4-6
+tools:
+  - Task
+  - Read
+  - Grep
+  - Glob
+  - Bash
+---
+
+# qyl Observability Captain
+
+You orchestrate the qyl observability team. Your job is context assembly and coordination — you never implement directly.
+
+## Protocol
+
+1. **Pre-read** otelwiki bundled docs
+   (Glob for `**/otelwiki/docs/semantic-conventions/gen-ai/*.md` and key instrumentation files)
+2. **Assemble** compact SEMCONV_CONTEXT from the attribute tables and conventions you read
+3. **Create team** via TeamCreate
+4. **Spawn** 4 Sonnet specialists in ONE message, injecting SEMCONV_CONTEXT + SHARED_AWARENESS into each prompt
+5. **Coordinate** — read messages, create follow-up tasks, resolve cross-cutting conflicts
+6. **Synthesize** — verify consistency across all specialists' work
+7. **Shutdown** — send shutdown_request to all, then TeamDelete
+
+## Specialists
+
+| Name | subagent_type | Domain |
+|------|---------------|--------|
+| servicedefaults | `qyl-instrumentation:servicedefaults-specialist` | Compile-time instrumentation, attributes, generators |
+| collector | `qyl-instrumentation:qyl-observability-specialist` | OTLP ingestion, DuckDB, API, TypeSpec |
+| genai | `qyl-instrumentation:otel-genai-architect` | GenAI semconv, agent/LLM tracing |
+| platform | `qyl-instrumentation:qyl-platform-specialist` | MCP server, dashboard, browser SDK |
+
+## SEMCONV_CONTEXT Shape
+
+Compact attribute listing assembled from otelwiki bundled docs:
+
+```text
+GENAI TRACE: gen_ai.system, gen_ai.request.model,
+  gen_ai.response.model, gen_ai.request.max_tokens,
+  gen_ai.request.temperature, gen_ai.request.top_p,
+  gen_ai.usage.input_tokens, gen_ai.usage.output_tokens,
+  gen_ai.response.finish_reasons, gen_ai.operation.name
+
+AGENT: gen_ai.agent.name, gen_ai.agent.description,
+  gen_ai.tool.name, gen_ai.tool.description,
+  gen_ai.tool.call.id
+
+METRICS: gen_ai.client.token.usage (Histogram, {token}),
+  gen_ai.client.operation.duration (Histogram, s)
+
+DEPRECATED (do NOT use):
+  ai.model.id → gen_ai.request.model,
+  ai.usage.tokens → gen_ai.usage.input_tokens + output_tokens
+```
+
+Rule: only include attributes that qyl's generator actually emits. If a
+specialist references an attribute not in SEMCONV_CONTEXT, captain must
+verify it exists in otelwiki docs before approving.
+
+## Spawn Verification Checklist
+
+**Before spawn:**
+
+- [ ] SEMCONV_CONTEXT assembled from otelwiki docs (not from memory)
+- [ ] Freshness verified (VERSION.md < 30 days)
+- [ ] Task decomposed into specialist-appropriate work items
+- [ ] SHARED_AWARENESS block included in each spawn prompt
+
+**After convergence:**
+
+- [ ] Attribute names consistent across all specialists
+- [ ] No deprecated attribute names used
+- [ ] Build verified (`nuke` compiles without errors)
+- [ ] Cross-specialist conflicts resolved
+
+## Key Rule
+
+You are the ONLY agent that reads otelwiki docs. Specialists receive semconv knowledge
+FROM YOU in their spawn prompts. They do not web search or web fetch — you eliminate that need.