wicked-garden 12.27.0

package/skills/platform/observability/refs/toolchain-discovery.md

@@ -0,0 +1,243 @@
+---
+phase_relevance: ["build", "review", "operate"]
+archetype_relevance: ["*"]
+---
+# Toolchain Discovery: Monitoring CLI Detection Patterns
+
+Detection patterns and usage examples for monitoring CLIs in the engineer's environment.
+All detection uses `command -v` — no external dependencies required.
+
+## Detection Script
+
+```bash
+# Discover all monitoring CLIs in current environment
+discover_monitoring_tools() {
+  echo "=== APM ==="
+  command -v datadog-agent &>/dev/null && echo "  datadog: $(command -v datadog-agent)"
+  command -v newrelic      &>/dev/null && echo "  newrelic: $(command -v newrelic)"
+  command -v dt            &>/dev/null && echo "  dynatrace: $(command -v dt)"
+
+  echo "=== Logging ==="
+  command -v splunk        &>/dev/null && echo "  splunk: $(command -v splunk)"
+  command -v elasticsearch &>/dev/null && echo "  elasticsearch: $(command -v elasticsearch)"
+  command -v logcli        &>/dev/null && echo "  loki: $(command -v logcli)"
+
+  echo "=== Metrics ==="
+  command -v promtool      &>/dev/null && echo "  prometheus: $(command -v promtool)"
+  command -v grafana-cli   &>/dev/null && echo "  grafana: $(command -v grafana-cli)"
+  command -v influx        &>/dev/null && echo "  influxdb: $(command -v influx)"
+
+  echo "=== Cloud ==="
+  command -v aws           &>/dev/null && echo "  cloudwatch: $(command -v aws)"
+  command -v gcloud        &>/dev/null && echo "  gcp: $(command -v gcloud)"
+  command -v az            &>/dev/null && echo "  azure: $(command -v az)"
+}
+```
+
+---
+
+## APM Tools
+
+### Datadog (`datadog-agent`)
+
+```bash
+# Agent status
+datadog-agent status
+
+# Check specific integration
+datadog-agent check postgres
+
+# Query metrics via API
+curl -G "https://api.datadoghq.com/api/v1/metrics/query" \
+  -H "DD-API-KEY: ${DD_API_KEY}" -H "DD-APPLICATION-KEY: ${DD_APP_KEY}" \
+  --data-urlencode "query=avg:system.cpu.user{host:web-01}" \
+  --data-urlencode "from=$(date -d '1 hour ago' +%s)" \
+  --data-urlencode "to=$(date +%s)"
+
+# Diagnose connectivity
+datadog-agent diagnose
+```
+
+### New Relic (`newrelic`)
+
+```bash
+# Auth check
+newrelic whoami
+
+# NRQL query
+newrelic nrql query \
+  --query "SELECT count(*) FROM Transaction WHERE appName='MyApp' SINCE 1 hour ago"
+
+# Open alerts
+newrelic alerts incidents list --state OPEN
+
+# Setup: newrelic profiles add --profile myprofile --apiKey "${NEW_RELIC_API_KEY}"
+```
+
+### Dynatrace (`dt`)
+
+```bash
+# Auth check
+dt auth
+
+# Query metrics
+dt metrics query --metric-selector "builtin:host.cpu.usage" --resolution 5m
+
+# Open problems
+dt problems list --status OPEN
+
+# Entity list
+dt entities list --entitySelector "type(SERVICE),tag(env:production)"
+```
+
+---
+
+## Logging Tools
+
+### Splunk (`splunk`)
+
+```bash
+# Status check
+splunk status
+
+# Search last hour of errors
+splunk search "index=main error" -earliest=-1h -latest=now
+
+# Export results
+splunk search "index=main sourcetype=syslog error" -earliest=-1h -output csv > errors.csv
+
+# REST API alternative
+curl -k -u "admin:${SPLUNK_PASSWORD}" "https://localhost:8089/services/search/jobs" \
+  -d "search=search index=main error | head 10" -d "output_mode=json"
+```
+
+### Elasticsearch / ELK
+
+```bash
+# Cluster health
+curl -s "http://localhost:9200/_cluster/health" | jq .
+
+# Query errors (last hour)
+curl -s -X GET "http://localhost:9200/logs-*/_search" \
+  -H "Content-Type: application/json" \
+  -d '{"query":{"bool":{"must":[{"match":{"level":"error"}}],
+        "filter":[{"range":{"@timestamp":{"gte":"now-1h"}}}]}}, "size":50}' \
+  | jq '.hits.hits[]._source'
+```
+
+### Loki (`logcli`)
+
+```bash
+# Query errors
+logcli query '{app="my-service"} |= "error"' --limit 100 --since=1h
+
+# Stream live
+logcli query '{app="my-service"}' --tail
+
+# List labels
+logcli labels app
+
+# export LOKI_ADDR="http://localhost:3100"
+```
+
+---
+
+## Metrics Tools
+
+### Prometheus (`promtool`)
+
+```bash
+# Validate config
+promtool check config prometheus.yml
+
+# Instant query (REST API)
+curl -s "http://localhost:9090/api/v1/query?query=up" | jq '.data.result[]'
+
+# Range query
+curl -s "http://localhost:9090/api/v1/query_range" \
+  --data-urlencode "query=rate(http_requests_total[5m])" \
+  --data-urlencode "start=$(date -d '1 hour ago' +%s)" \
+  --data-urlencode "end=$(date +%s)" \
+  --data-urlencode "step=60" | jq '.data.result[]'
+```
+
+### Grafana (`grafana-cli`)
+
+```bash
+# Health check
+curl -s "http://localhost:3000/api/health" | jq .
+
+# List dashboards
+curl -s -u "admin:${GRAFANA_PASSWORD}" \
+  "http://localhost:3000/api/search?type=dash-db" | jq '.[].title'
+```
+
+---
+
+## Cloud Monitoring Tools
+
+### AWS CloudWatch (`aws`)
+
+```bash
+# List log groups
+aws logs describe-log-groups --query 'logGroups[*].logGroupName' --output table
+
+# Filter errors from a log group
+aws logs filter-log-events \
+  --log-group-name "/aws/lambda/my-function" \
+  --filter-pattern "ERROR" \
+  --start-time "$(date -d '1 hour ago' +%s000)" --limit 50
+
+# Get metric stats
+aws cloudwatch get-metric-statistics \
+  --namespace "AWS/Lambda" --metric-name "Errors" \
+  --dimensions Name=FunctionName,Value=my-function \
+  --start-time "$(date -u -d '1 hour ago' +%Y-%m-%dT%H:%M:%SZ)" \
+  --end-time "$(date -u +%Y-%m-%dT%H:%M:%SZ)" \
+  --period 300 --statistics Sum
+```
+
+### Google Cloud Monitoring (`gcloud`)
+
+```bash
+# Recent errors
+gcloud logging read "severity>=ERROR" --limit=50 --freshness=1h
+
+# Filter by resource
+gcloud logging read \
+  'resource.type="k8s_container" AND severity="ERROR"' \
+  --limit 50 --project="${GOOGLE_PROJECT}"
+```
+
+### Azure Monitor (`az`)
+
+```bash
+# Log Analytics query
+az monitor log-analytics query \
+  --workspace "${AZURE_WORKSPACE_ID}" \
+  --analytics-query "AzureDiagnostics | where Level == 'Error' | take 50" \
+  --output table
+
+# Get metric values
+az monitor metrics list \
+  --resource "${AZURE_RESOURCE_ID}" --metric "requests" --interval PT5M \
+  --start-time "$(date -u -d '1 hour ago' +%Y-%m-%dT%H:%M:%SZ)"
+```
+
+---
+
+## Quick Reference
+
+| Tool | Binary | Category | Key Operation |
+|------|--------|----------|---------------|
+| Datadog | `datadog-agent` | APM | `status`, REST metrics API |
+| New Relic | `newrelic` | APM | `nrql query` |
+| Dynatrace | `dt` | APM | `metrics query`, `problems list` |
+| Splunk | `splunk` | Logging | `search "index=main ..."` |
+| Elasticsearch | n/a | Logging | REST `/_search` |
+| Loki | `logcli` | Logging | `query '{app="..."}` |
+| Prometheus | `promtool` | Metrics | REST `/api/v1/query` |
+| Grafana | `grafana-cli` | Metrics | REST `/api/search` |
+| AWS CloudWatch | `aws` | Cloud | `logs filter-log-events` |
+| GCP Monitoring | `gcloud` | Cloud | `logging read` |
+| Azure Monitor | `az` | Cloud | `monitor log-analytics query` |

package/skills/platform/prereq-doctor/SKILL.md

@@ -0,0 +1,57 @@
+---
+name: prereq-doctor
+description: |
+  Diagnose missing tools and dependencies, offer to install them.
+
+  Use when: "command not found", "ModuleNotFoundError", "missing tool",
+  "install dependency", "prereq check", "setup validation"
+phase_relevance: ["build", "review", "operate"]
+archetype_relevance: ["*"]
+---
+
+# Prereq Doctor
+
+Diagnoses missing CLI tools and Python dependencies, offers to install them.
+
+## When to Use
+
+- PostToolUseFailure hook detects a missing-tool error pattern
+- Setup needs to validate a selected integration (issue tracker, CLI tool)
+- Any command fails with "command not found" or "ModuleNotFoundError"
+- User asks to check or install prerequisites
+
+## How It Works
+
+1. **Diagnose**: Parse the error or tool name to identify what's missing
+2. **Lookup**: Match against the known tool registry (see refs/tool-registry.md)
+3. **Detect platform**: macOS (brew) vs Linux (apt/dnf) vs generic (pip/npm/cargo)
+4. **Ask**: Present the install command and ask the user for permission
+5. **Install**: Run the install command if approved
+6. **Verify**: Confirm the tool is now available
+
+## Quick Reference
+
+```bash
+# Diagnose a specific tool
+sh "${CLAUDE_PLUGIN_ROOT}/scripts/_python.sh" "${CLAUDE_PLUGIN_ROOT}/scripts/platform/prereq_doctor.py" check <tool>
+
+# Diagnose from an error message
+sh "${CLAUDE_PLUGIN_ROOT}/scripts/_python.sh" "${CLAUDE_PLUGIN_ROOT}/scripts/platform/prereq_doctor.py" diagnose "<error_text>"
+
+# Check all prerequisites for wicked-garden
+sh "${CLAUDE_PLUGIN_ROOT}/scripts/_python.sh" "${CLAUDE_PLUGIN_ROOT}/scripts/platform/prereq_doctor.py" check-all
+```
+
+## Usage from Commands
+
+Commands should NOT inline install logic. Instead:
+
+```
+Skill(skill="wicked-garden:platform:prereq-doctor", args="check gh")
+```
+
+Or let the PostToolUseFailure hook catch it automatically — just try to use the tool.
+
+## Detailed Reference
+
+- refs/tool-registry.md — Full tool→install mapping with platform variants

package/skills/platform/prereq-doctor/refs/tool-registry.md

@@ -0,0 +1,58 @@
+---
+phase_relevance: ["build", "review", "operate"]
+archetype_relevance: ["*"]
+---
+# Tool Registry
+
+Maps tool names to install commands per platform. Used by `prereq_doctor.py`.
+
+## CLI Tools
+
+| Tool | CLI | macOS (brew) | Linux (apt) | Generic | Docs |
+|------|-----|-------------|-------------|---------|------|
+| GitHub | `gh` | `brew install gh` | `apt install gh` | [manual](https://cli.github.com) | https://cli.github.com |
+| Jira | `jira` | `brew install ankitpokhrel/jira-cli/jira-cli` | `go install github.com/ankitpokhrel/jira-cli/v2@latest` | — | https://github.com/ankitpokhrel/jira-cli |
+| Linear | `linear` | `npm install -g @linear/cli` | `npm install -g @linear/cli` | `npm install -g @linear/cli` | https://developers.linear.app |
+| Azure DevOps | `az` | `brew install azure-cli` | `curl -sL https://aka.ms/InstallAzureCLIDeb \| sudo bash` | [manual](https://learn.microsoft.com/en-us/cli/azure/install-azure-cli) | https://learn.microsoft.com/en-us/azure/devops/cli |
+| Rally | `rally` | `pip install rallydev` | `pip install rallydev` | `pip install rallydev` | https://pypi.org/project/rallydev/ |
+| GitLab | `glab` | `brew install glab` | `apt install glab` | [manual](https://gitlab.com/gitlab-org/cli) | https://gitlab.com/gitlab-org/cli |
+| Shortcut | `sc` | `brew install shortcut-cli` | — | `npm install -g @shortcut/cli` | https://github.com/shortcut/cli |
+| DuckDB | `duckdb` | `brew install duckdb` | `apt install duckdb` | [manual](https://duckdb.org/docs/installation) | https://duckdb.org |
+| uv | `uv` | `brew install uv` | `curl -LsSf https://astral.sh/uv/install.sh \| sh` | `curl -LsSf https://astral.sh/uv/install.sh \| sh` | https://docs.astral.sh/uv |
+| tree-sitter | `tree-sitter` | `brew install tree-sitter` | `npm install -g tree-sitter-cli` | `cargo install tree-sitter-cli` | https://tree-sitter.github.io |
+
+## Python Dependencies
+
+| Package | Import | Install | Used By |
+|---------|--------|---------|---------|
+| rapidfuzz | `from rapidfuzz import ...` | `uv sync` (from root pyproject.toml) | search |
+| pydantic | `from pydantic import ...` | `uv sync` | search, smaht |
+| tree-sitter | `import tree_sitter` | `uv sync` | search |
+| aiofiles | `import aiofiles` | `uv sync` | search |
+| pyyaml | `import yaml` | `uv sync` | search |
+| lxml | `from lxml import ...` | `uv sync` | search |
+| kreuzberg | `import kreuzberg` | `uv sync` | search |
+
+## Error Pattern → Tool Mapping
+
+| Error Pattern | Missing Tool | Fix |
+|---------------|-------------|-----|
+| `command not found: gh` | gh CLI | Install gh |
+| `command not found: uv` | uv | Install uv |
+| `command not found: jira` | jira-cli | Install jira-cli |
+| `command not found: az` | azure-cli | Install az |
+| `command not found: glab` | glab | Install glab |
+| `ModuleNotFoundError: No module named 'rapidfuzz'` | Python deps | Run `uv sync` |
+| `ModuleNotFoundError: No module named 'pydantic'` | Python deps | Run `uv sync` |
+| `ModuleNotFoundError: No module named 'yaml'` | Python deps | Run `uv sync` |
+| `ModuleNotFoundError: No module named 'tree_sitter'` | Python deps | Run `uv sync` |
+
+## Azure DevOps Extension
+
+After installing `az`, the azure-devops extension is also needed:
+
+```bash
+az extension add --name azure-devops
+```
+
+This is handled automatically by the prereq-doctor when `ado` is the target.

package/skills/platform/traces/refs/traces.md

@@ -0,0 +1,101 @@
+# Distributed Trace Analysis Rubric
+
+Analyze distributed traces for latency, bottleneck detection, and service dependencies.
+
+## Step 1: Discover Tracing Sources
+
+Use `ListMcpResourcesTool` and scan for tracing capability:
+- Jaeger, Zipkin, Tempo
+- Datadog APM, New Relic
+- AWS X-Ray, GCP Cloud Trace
+- OpenTelemetry Collector
+
+## Step 2: Determine Analysis Type
+
+Based on argument:
+- **Service name**: Analyze traces for a specific service
+- **Trace ID**: Deep dive into a single trace
+- **"slow"**: Find and analyze the slowest p99 requests
+
+## Step 3: Investigation Checklist
+
+For each target trace or service:
+- [ ] Latency breakdown by span — where is time spent?
+- [ ] Service dependency chain — request flow through all services
+- [ ] Bottleneck identification — slowest spans as % of total
+- [ ] Error propagation — failure chain analysis
+- [ ] N+1 query patterns — repeated DB queries per loop iteration
+- [ ] Sequential vs parallel opportunities — spans that could run concurrently
+
+## Step 4: Fallback (No Tracing Available)
+
+Infer architecture from code patterns:
+```bash
+# Find service calls
+grep -r "fetch\|axios\|http\|grpc\|requests\." --include="*.{js,ts,py,go}" -l
+
+# Find database queries
+grep -r "query\|select\|insert\|db\." --include="*.{js,ts,py,go}" -l
+```
+
+Report inferred dependency graph and flag where tracing instrumentation is missing.
+
+## Output Format
+
+```markdown
+## Trace Analysis
+
+**Target**: {service name | trace ID | "slow requests"}
+**Time Range**: {period}
+**Source**: {tracing backend | "code inference (no tracing found)"}
+
+### Latency Breakdown
+| Span | Duration | % of Total |
+|------|----------|------------|
+| {service} | {ms} | {%} |
+| └─ {child-span} | {ms} | {%} |
+
+### Service Dependencies
+```
+{ascii dependency diagram}
+service-a → service-b → db
+          → cache
+```
+
+### Bottlenecks Identified
+1. **{span name}** — {duration} ({%} of total)
+   - Evidence: {trace ID or pattern}
+   - Fix: {recommendation}
+
+### Patterns Detected
+- **N+1 queries**: {location — e.g., `src/inventory.ts:45`, 12 sequential queries}
+- **Slow external calls**: {service name, avg latency}
+- **Sequential when parallel possible**: {location}
+- **Missing instrumentation**: {service boundaries not traced}
+
+### Optimization Recommendations
+| Issue | Expected Improvement | Effort |
+|-------|---------------------|--------|
+| {issue} | {reduction} | Low/Med/High |
+
+1. {highest-impact fix with before/after code if applicable}
+```
+
+## Common Patterns
+
+### N+1 Query
+**Symptom**: Many short repeated spans (same query, N iterations).
+**Fix**: Batch the query — `WHERE id IN (?)` instead of loop.
+**Expected**: Often 80-90% latency reduction on the affected span.
+
+### Synchronous Fan-out
+**Symptom**: Several external calls sequential that could be parallel.
+**Fix**: `Promise.all()` / `asyncio.gather()` / goroutines.
+
+### Missing Circuit Breaker
+**Symptom**: One downstream timeout causes caller to also timeout.
+**Fix**: Add circuit breaker (Resilience4j, Hystrix, custom) with fallback.
+
+### Cold-Start Penalty
+**Symptom**: First request to a service much slower than subsequent.
+**Fix**: Warm-up endpoints, connection pool pre-warming, lazy init moved to startup.

package/skills/product/acceptance-criteria/SKILL.md

@@ -0,0 +1,193 @@
+---
+name: acceptance-criteria
+description: |
+  Define testable acceptance criteria from requirements and design.
+  Bridge product requirements with QE test scenarios.
+
+  Use when: "define acceptance criteria", "how do we know it's done",
+  "what should QE test", "definition of done"
+phase_relevance: ["clarify", "design", "review"]
+archetype_relevance: ["*"]
+---
+
+# Acceptance Criteria Skill
+
+Transform requirements into testable acceptance criteria.
+
+## Core Concept
+
+Acceptance criteria are the contract between product and delivery:
+- Product: "Here's what success looks like"
+- QE: "Here's how we verify it"
+- Engineering: "Here's what we must deliver"
+
+## Given/When/Then Format
+
+```
+Given [precondition/context]
+When [action/event]
+Then [expected outcome]
+```
+
+**Why this format?**
+- Forces specificity
+- Testable by definition
+- Clear success criteria
+- Language-agnostic
+
+## Process
+
+### 1. Read Requirements
+
+Understand:
+- User stories
+- Design documents
+- Business rules
+- Constraints
+
+### 2. Identify Scenarios
+
+For each requirement, consider:
+- **Happy path**: Normal, expected flow
+- **Error conditions**: Invalid inputs, failures
+- **Edge cases**: Boundaries, empty states
+- **Non-functional**: Performance, security, usability
+
+### 3. Write Criteria
+
+Format each scenario:
+```
+Given [specific context]
+When [specific action]
+Then [specific, measurable outcome]
+```
+
+### 4. Validate
+
+Check each criterion:
+- [ ] Specific (not vague)
+- [ ] Testable (can verify)
+- [ ] Measurable (clear pass/fail)
+- [ ] Independent (standalone)
+- [ ] Complete (covers scenario)
+
+### 5. Organize by Priority
+
+- **P0**: Must have (blocker if missing)
+- **P1**: Should have (important)
+- **P2**: Nice to have (enhancement)
+
+## Example: Login Feature
+
+```markdown
+### US1: User Authentication
+
+**Happy Path (P0)**:
+AC1: Given valid credentials, When user submits login, Then user redirected to dashboard
+AC2: Given successful login, When checking session, Then session valid for 30 minutes
+
+**Error Handling (P0)**:
+AC3: Given invalid password, When user submits login, Then error message "Invalid credentials"
+AC4: Given account locked, When user submits login, Then error message "Account locked"
+AC5: Given 3 failed attempts, When user tries again, Then account locked for 15 minutes
+
+**Edge Cases (P1)**:
+AC6: Given empty email field, When user submits, Then error "Email required"
+AC7: Given malformed email, When user submits, Then error "Invalid email format"
+AC8: Given concurrent logins, When second login occurs, Then first session invalidated
+
+**Non-Functional (P1)**:
+AC9: Given 1000 concurrent logins, When system under load, Then response time < 2 seconds
+AC10: Given login attempt, When credentials checked, Then password encrypted in transit
+```
+
+## Common Patterns
+
+**Data Creation**:
+```
+Given user on create form
+When user enters valid data and submits
+Then new record saved and confirmation shown
+```
+
+**Data Validation**:
+```
+Given user on form with required fields
+When user submits without filling required field
+Then error message shown and form not submitted
+```
+
+**Authorization**:
+```
+Given user without admin role
+When user attempts admin action
+Then access denied message shown
+```
+
+**API Response**:
+```
+Given valid API request
+When endpoint called
+Then 200 status and expected JSON schema returned
+```
+
+## Integration with QE
+
+Acceptance criteria feed directly into test scenarios:
+
+```bash
+# Product defines AC
+/wicked-garden:product:acceptance phases/design/
+
+# Generate test scenarios from AC
+/wicked-testing:plan
+```
+
+**Flow**:
+1. Product: Write acceptance criteria
+2. QE: Review and generate test scenarios
+3. Engineering: Implement to meet criteria
+4. QE: Verify against criteria
+
+## Quality Checklist
+
+Good acceptance criteria:
+- [ ] Use Given/When/Then format
+- [ ] Specific and unambiguous
+- [ ] Testable with clear pass/fail
+- [ ] Cover happy path, errors, edges
+- [ ] Include non-functional requirements
+- [ ] Prioritized by criticality
+- [ ] Reviewed by QE for testability
+
+## Output Format
+
+```markdown
+## Acceptance Criteria
+
+### User Story: {Story Title}
+
+**Happy Path**:
+- AC1: Given {context}, When {action}, Then {outcome} [P0]
+
+**Error Conditions**:
+- AC2: Given {error}, When {action}, Then {handling} [P0]
+
+**Edge Cases**:
+- AC3: Given {edge}, When {action}, Then {behavior} [P1]
+
+**Non-Functional**:
+- AC4: Given {load}, When {action}, Then {performance} [P1]
+
+**Test Data Requirements**:
+- {Data needed for testing}
+
+**QE Handoff Notes**:
+- {Special testing considerations}
+```
+
+## Progressive Disclosure
+
+- **SKILL.md** (this file): Quick reference
+- **refs/ac-examples.md**: More examples by domain
+- **refs/ac-anti-patterns.md**: Common mistakes to avoid