opendevbrowser 0.0.15 → 0.0.16

package/skills/opendevbrowser-research/SKILL.md

@@ -0,0 +1,73 @@
+---
+name: opendevbrowser-research
+description: Deterministic multi-source research workflow with strict timebox and artifact outputs.
+version: 2.0.0
+---
+
+# Research Skill
+
+Use this skill when you need benchmark-style research across `web|community|social|shopping` with strict timebox semantics and stable output modes.
+
+## Pack Contents
+
+- `artifacts/research-workflows.md`
+- `assets/templates/compact.md`
+- `assets/templates/context.json`
+- `assets/templates/report.md`
+- `scripts/run-research.sh`
+- `scripts/render-output.sh`
+- `scripts/write-artifacts.sh`
+- `scripts/validate-skill-assets.sh`
+- Shared robustness matrix: `../opendevbrowser-best-practices/artifacts/browser-agent-known-issues-matrix.md`
+
+## Fast Start
+
+```bash
+./skills/opendevbrowser-research/scripts/validate-skill-assets.sh
+./skills/opendevbrowser-research/scripts/run-research.sh "browser automation" 30 context
+./skills/opendevbrowser-research/scripts/render-output.sh "browser automation" compact
+```
+
+## Core Rules
+
+- Define timebox first (`--days` or `--from/--to`).
+- Prefer explicit sources for high-stakes claims.
+- Persist artifacts and return reproducible paths.
+- Mark unsupported claims as tentative; do not overstate certainty.
+- Honor bounded retries and backoff windows under 429 pressure.
+
+## Parallel Multitab Alignment
+
+- Apply shared concurrency policy from `../opendevbrowser-best-practices/SKILL.md` ("Parallel Operations").
+- Run research acceptance in `managed`, `extension`, and `cdpConnect` where browser-backed evidence capture is used.
+- Keep provider query orchestration mode-agnostic; isolate browser interaction per session worker.
+
+## Robustness Coverage (Known-Issue Matrix)
+
+Matrix source: `../opendevbrowser-best-practices/artifacts/browser-agent-known-issues-matrix.md`
+
+- `ISSUE-06`: upstream throttling and retry discipline
+- `ISSUE-09`: pagination/result drift across sources
+- `ISSUE-10`: locale/currency normalization consistency
+- `ISSUE-12`: stale evidence and claim traceability
+
+## Workflow
+
+1. Resolve timebox (`days` or `from/to`).
+2. Choose sources (`auto|web|community|social|shopping|all`).
+3. Run `opendevbrowser research run`.
+4. Return requested mode output and artifact path.
+
+## Commands
+
+```bash
+opendevbrowser research run --topic "<topic>" --days 30 --mode context
+opendevbrowser research run --topic "<topic>" --source-selection all --mode json
+opendevbrowser research run --topic "<topic>" --sources web,shopping --mode md
+```
+
+## Notes
+
+- `auto` resolves to `web|community|social` in v1.
+- Use `--source-selection all` or `--sources shopping,...` to include shopping.
+- Use `--mode path` with `scripts/write-artifacts.sh` when you need replayable handoff bundles.

package/skills/opendevbrowser-research/artifacts/research-workflows.md

@@ -0,0 +1,29 @@
+# Research Workflows
+
+## Deterministic baseline workflow
+
+1. Define topic and strict time window
+2. Resolve source selection (`auto|all|explicit`)
+3. Run research workflow command
+4. Persist context/report artifacts
+5. Validate source diversity and freshness
+
+## Cross-source corroboration workflow
+
+1. Identify claims from first-pass output
+2. Require at least two independent source records for critical claims
+3. Mark unsupported claims as tentative
+4. Escalate when corroboration is missing
+
+## Backoff/retry workflow
+
+1. Detect repeated 429/upstream throttling
+2. Honor retry windows and bounded retries
+3. Resume from persisted context artifact
+4. Report partial coverage when limits persist
+
+## Compact handoff workflow
+
+1. Produce compact summary with key findings
+2. Include unresolved risks and missing evidence
+3. Attach artifact paths for replay

package/skills/opendevbrowser-research/assets/templates/compact.md

@@ -0,0 +1,7 @@
+# Compact Research Template
+
+- Top findings:
+- Source diversity:
+- Key risks:
+- Rate-limit/backoff notes:
+- Open evidence gaps:

package/skills/opendevbrowser-research/assets/templates/context.json

@@ -0,0 +1,18 @@
+{
+  "topic": "",
+  "timebox": {
+    "days": 30
+  },
+  "issue_ids": [
+    "ISSUE-06",
+    "ISSUE-09",
+    "ISSUE-10",
+    "ISSUE-12"
+  ],
+  "highlights": [],
+  "records": [],
+  "meta": {
+    "source_count": 0,
+    "warnings": []
+  }
+}

package/skills/opendevbrowser-research/assets/templates/report.md

@@ -0,0 +1,9 @@
+# Research Report
+
+## Executive Summary
+
+## Findings
+
+## Confidence and Gaps
+
+## Sources

package/skills/opendevbrowser-research/examples/sample-input.json

@@ -0,0 +1,6 @@
+{
+  "topic": "ai browser automation",
+  "days": 30,
+  "sourceSelection": "auto",
+  "mode": "context"
+}

package/skills/opendevbrowser-research/examples/sample-output.md

@@ -0,0 +1,4 @@
+# Sample Output
+
+1. Example finding one
+2. Example finding two

package/skills/opendevbrowser-research/scripts/render-output.sh

@@ -0,0 +1,12 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ $# -lt 2 ]]; then
+  echo "Usage: render-output.sh <topic> <mode>"
+  exit 1
+fi
+
+TOPIC="$1"
+MODE="$2"
+
+opendevbrowser research run --topic "$TOPIC" --mode "$MODE"

package/skills/opendevbrowser-research/scripts/run-research.sh

@@ -0,0 +1,23 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ $# -lt 1 ]]; then
+  echo "Usage: run-research.sh <topic> [days] [mode] [source-selection] [sources]"
+  exit 1
+fi
+
+TOPIC="$1"
+DAYS="${2:-30}"
+MODE="${3:-context}"
+SOURCE_SELECTION="${4:-}"
+SOURCES="${5:-}"
+
+cmd=(opendevbrowser research run --topic "$TOPIC" --days "$DAYS" --mode "$MODE")
+if [[ -n "$SOURCE_SELECTION" ]]; then
+  cmd+=(--source-selection "$SOURCE_SELECTION")
+fi
+if [[ -n "$SOURCES" ]]; then
+  cmd+=(--sources "$SOURCES")
+fi
+
+"${cmd[@]}"

package/skills/opendevbrowser-research/scripts/validate-skill-assets.sh

@@ -0,0 +1,48 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+root="$(cd "$(dirname "${BASH_SOURCE[0]}")/.." && pwd)"
+skill_file="$root/SKILL.md"
+
+required=(
+  "artifacts/research-workflows.md"
+  "assets/templates/compact.md"
+  "assets/templates/context.json"
+  "assets/templates/report.md"
+  "scripts/run-research.sh"
+  "scripts/render-output.sh"
+  "scripts/write-artifacts.sh"
+  "scripts/validate-skill-assets.sh"
+)
+
+status=0
+for rel in "${required[@]}"; do
+  if [[ ! -f "$root/$rel" ]]; then
+    echo "Missing required asset: $rel" >&2
+    status=1
+  fi
+  if ! grep -Fq "$rel" "$skill_file"; then
+    echo "SKILL.md missing reference: $rel" >&2
+    status=1
+  fi
+done
+
+for rel in scripts/run-research.sh scripts/render-output.sh scripts/write-artifacts.sh scripts/validate-skill-assets.sh; do
+  if [[ -f "$root/$rel" && ! -x "$root/$rel" ]]; then
+    echo "Script is not executable: $rel" >&2
+    status=1
+  fi
+done
+
+if [[ -f "$root/assets/templates/context.json" ]]; then
+  if ! node -e 'const fs=require("fs"); JSON.parse(fs.readFileSync(process.argv[1], "utf8"));' "$root/assets/templates/context.json" >/dev/null 2>&1; then
+    echo "Invalid JSON template: assets/templates/context.json" >&2
+    status=1
+  fi
+fi
+
+if [[ $status -ne 0 ]]; then
+  exit $status
+fi
+
+echo "Research skill assets validated."

package/skills/opendevbrowser-research/scripts/write-artifacts.sh

@@ -0,0 +1,29 @@
+#!/usr/bin/env bash
+set -euo pipefail
+
+if [[ $# -lt 2 ]]; then
+  echo "Usage: write-artifacts.sh <topic> <output-dir>"
+  exit 1
+fi
+
+TOPIC="$1"
+OUTDIR="$2"
+
+json_output="$(opendevbrowser research run --topic "$TOPIC" --mode path --output-dir "$OUTDIR" --output-format json)"
+printf '%s\n' "$json_output"
+
+artifact_path="$(printf '%s\n' "$json_output" | node -e 'const fs=require("fs");const lines=fs.readFileSync(0,"utf8").split(/\r?\n/).map((line)=>line.trim()).filter(Boolean);let payload=null;for(const line of lines){try{payload=JSON.parse(line);}catch{}}const p=payload?.data?.path; if(typeof p==="string") process.stdout.write(p);')"
+if [[ -z "$artifact_path" || ! -d "$artifact_path" ]]; then
+  manifest_path="$(find "$OUTDIR" -maxdepth 4 -type f -name bundle-manifest.json 2>/dev/null | head -n 1)"
+  if [[ -n "$manifest_path" ]]; then
+    artifact_path="$(dirname "$manifest_path")"
+  fi
+fi
+
+if [[ -z "$artifact_path" || ! -d "$artifact_path" ]]; then
+  echo "Artifact path not found for output dir: $OUTDIR" >&2
+  exit 2
+fi
+
+node -e 'console.log(JSON.stringify({ data: { path: process.argv[1] } }));' "$artifact_path"
+echo "Artifacts ready: $artifact_path"

package/skills/opendevbrowser-shopping/SKILL.md

@@ -0,0 +1,118 @@
+---
+name: opendevbrowser-shopping
+description: Deterministic multi-provider shopping and deal-comparison workflow.
+version: 2.0.0
+---
+
+# Shopping Skill
+
+Use this skill for robust deal hunting across providers with market-baseline validation and savings analysis.
+
+## Pack Contents
+
+- `artifacts/deal-hunting-workflows.md`
+- `assets/templates/deals-context.json`
+- `assets/templates/deals-table.md`
+- `assets/templates/market-analysis.json`
+- `assets/templates/deal-thresholds.json`
+- `scripts/run-shopping.sh`
+- `scripts/normalize-offers.sh`
+- `scripts/render-deals.sh`
+- `scripts/analyze-market.sh`
+- `scripts/run-deal-hunt.sh`
+- `scripts/validate-skill-assets.sh`
+- Shared robustness matrix: `../opendevbrowser-best-practices/artifacts/browser-agent-known-issues-matrix.md`
+
+## Fast Start
+
+```bash
+./skills/opendevbrowser-shopping/scripts/validate-skill-assets.sh
+./skills/opendevbrowser-shopping/scripts/run-shopping.sh "wireless earbuds" context best_deal
+./skills/opendevbrowser-shopping/scripts/run-deal-hunt.sh "wireless earbuds" "shopping/amazon,shopping/walmart"
+```
+
+## Deal-Hunting Model
+
+Use a two-layer check for each offer:
+
+1. Provider discount check
+- Compare listed total to provider anchor price (MSRP/list/original) when available.
+- Capture absolute savings and percentage savings.
+
+2. Market baseline check
+- Compare listed total against cross-provider market average and median.
+- Flag offers that are truly cheaper than market, not just marked "on sale".
+
+## Parallel Multitab Alignment
+
+- Apply shared concurrency policy from `../opendevbrowser-best-practices/SKILL.md` ("Parallel Operations").
+- Validate shopping workflows across `managed`, `extension`, and `cdpConnect` when browser-backed provider paths are exercised.
+- Keep one session per worker for parallel offer collection and avoid session-level target contention.
+
+## Savings Math
+
+Per offer:
+- `total_price = item_price + shipping`
+- `anchor_savings_abs = max(anchor_price - total_price, 0)`
+- `anchor_savings_pct = anchor_savings_abs / anchor_price * 100`
+
+Per market group (same currency):
+- `market_avg = average(total_price)`
+- `market_median = median(total_price)`
+- `market_savings_abs = market_avg - offer_total`
+- `market_savings_pct = market_savings_abs / market_avg * 100`
+
+This captures both:
+- high-percentage discounts (for example 50% off)
+- high-absolute savings (for example $500 saved)
+
+## Robustness Coverage (Known-Issue Matrix)
+
+Matrix source: `../opendevbrowser-best-practices/artifacts/browser-agent-known-issues-matrix.md`
+
+- `ISSUE-06`: rate-limit/backoff handling while collecting offers
+- `ISSUE-09`: dedupe and pagination drift controls in offer collection
+- `ISSUE-10`: currency normalization and same-currency grouping
+- `ISSUE-11`: weak/missing anchor price detection
+- `ISSUE-12`: stale price and unsupported claim controls
+
+## Canonical Workflow
+
+1. Run shopping search across selected providers.
+2. Normalize offers into stable records.
+3. Compute market analysis with `analyze-market.sh`.
+4. Render markdown/json summary for user decision.
+
+```bash
+opendevbrowser shopping run --query "<query>" --providers shopping/amazon,shopping/walmart --mode json --output-format json
+```
+
+## Classification Heuristics
+
+Default tags from analysis script:
+- `high_percent` when anchor discount percent exceeds threshold.
+- `high_absolute` when anchor discount absolute exceeds threshold.
+- `high_value` when both are true.
+- `market_beating` when offer is materially below market average.
+
+Threshold defaults are in `assets/templates/deal-thresholds.json`.
+
+Confidence model:
+- score combines sample size, anchor coverage, and freshness coverage.
+- warnings call out low-sample, missing-anchor, and stale/missing timestamp risk.
+
+## Good Deal Decision Rules
+
+Mark as strong only when at least one is true:
+- anchor discount is material and market gap is positive
+- market price is materially below average/median even without anchor
+
+Avoid false positives:
+- anchor discount exists but market total is not competitive
+- low total due to unavailable stock or hidden constraints
+
+## References
+
+- FTC Guides Against Deceptive Pricing (16 CFR 233): https://www.ecfr.gov/current/title-16/chapter-I/subchapter-B/part-233
+- NIST SP 1181 (unit pricing and value comparison): https://www.nist.gov/publications/unit-pricing-guide
+- Schema.org Offer (price metadata): https://schema.org/Offer

package/skills/opendevbrowser-shopping/artifacts/deal-hunting-workflows.md

@@ -0,0 +1,37 @@
+# Deal Hunting Workflows
+
+## Baseline deal workflow
+
+1. Query providers
+2. Normalize offers
+3. Compute market averages/medians
+4. Rank by true savings
+5. Attach confidence tier and warnings per currency group
+
+## Cross-provider verification workflow
+
+1. Start from discounted listing
+2. Query same product across alternate providers
+3. Compare totals in same currency
+4. Report verified savings and confidence
+
+## High-value prioritization workflow
+
+1. Compute percent discount
+2. Compute absolute savings
+3. Tag high-value if both thresholds pass
+4. Present top-ranked offers first
+
+## Anchor reliability workflow
+
+1. Detect whether anchor/list price exists per offer
+2. Compute anchor coverage by currency group
+3. Distinguish anchor-only discounts from market-beating discounts
+4. Warn when anchor evidence is weak
+
+## Freshness workflow
+
+1. Capture offer retrieval timestamp when available
+2. Compute price age hours
+3. Flag stale or missing timestamps
+4. Lower confidence tier when freshness coverage is low

package/skills/opendevbrowser-shopping/assets/templates/deal-thresholds.json

@@ -0,0 +1,8 @@
+{
+  "high_percent_threshold": 40,
+  "high_absolute_threshold": 100,
+  "min_market_gap_percent": 5,
+  "min_offer_count_for_confidence": 3,
+  "max_price_age_hours_for_freshness": 24,
+  "min_anchor_coverage_for_confidence": 0.5
+}

package/skills/opendevbrowser-shopping/assets/templates/deals-context.json

@@ -0,0 +1,9 @@
+{
+  "query": "",
+  "highlights": [],
+  "offers": [],
+  "market": {
+    "currency_summaries": []
+  },
+  "meta": {}
+}

package/skills/opendevbrowser-shopping/assets/templates/deals-table.md

@@ -0,0 +1,4 @@
+# Deals Table
+
+| Provider | Product | Total | Market Avg Gap | Anchor Discount | Deal Score |
+|---|---|---:|---:|---:|---:|

package/skills/opendevbrowser-shopping/assets/templates/market-analysis.json

@@ -0,0 +1,30 @@
+{
+  "generated_at": "",
+  "offers_count": 0,
+  "currency_summaries": [
+    {
+      "currency": "USD",
+      "offer_count": 0,
+      "market_average_total": 0,
+      "market_median_total": 0,
+      "best_offer": {
+        "provider": "",
+        "title": "",
+        "total": 0
+      },
+      "confidence": {
+        "score": 0,
+        "tier": "low",
+        "sample_size": 0,
+        "anchor_coverage": 0,
+        "fresh_price_coverage": 0,
+        "warnings": []
+      },
+      "savings_vs_market_average": {
+        "absolute": 0,
+        "percent": 0
+      },
+      "top_discounts": []
+    }
+  ]
+}

package/skills/opendevbrowser-shopping/examples/sample-deals.md

@@ -0,0 +1,4 @@
+# Sample Deals
+
+1. Provider A - $49.99
+2. Provider B - $52.00

package/skills/opendevbrowser-shopping/examples/sample-query.json

@@ -0,0 +1,5 @@
+{
+  "query": "wireless earbuds",
+  "sort": "best_deal",
+  "mode": "context"
+}