claude-code-arcane 1.0.0

package/skills/schema-markup/scripts/schema_validator.py

@@ -0,0 +1,442 @@
+#!/usr/bin/env python3
+"""
+schema_validator.py — Extracts and validates JSON-LD structured data from HTML.
+
+Usage:
+    python3 schema_validator.py [file.html]
+    cat page.html | python3 schema_validator.py
+
+If no file is provided, runs on embedded sample HTML for demonstration.
+
+Output: Human-readable validation report + JSON summary.
+Scoring: 0-100 per schema block based on required/recommended field coverage.
+"""
+
+import json
+import sys
+import re
+import select
+from html.parser import HTMLParser
+from typing import List, Dict, Any, Optional
+
+
+# ─── Required and recommended fields per schema type ─────────────────────────
+
+SCHEMA_RULES: Dict[str, Dict[str, List[str]]] = {
+    "Article": {
+        "required": ["headline", "image", "datePublished", "author"],
+        "recommended": ["dateModified", "publisher", "description", "url", "mainEntityOfPage"],
+    },
+    "BlogPosting": {
+        "required": ["headline", "image", "datePublished", "author"],
+        "recommended": ["dateModified", "publisher", "description", "url", "mainEntityOfPage"],
+    },
+    "NewsArticle": {
+        "required": ["headline", "image", "datePublished", "author"],
+        "recommended": ["dateModified", "publisher", "description", "url"],
+    },
+    "HowTo": {
+        "required": ["name", "step"],
+        "recommended": ["description", "image", "totalTime", "tool", "supply", "estimatedCost"],
+    },
+    "FAQPage": {
+        "required": ["mainEntity"],
+        "recommended": [],
+    },
+    "Product": {
+        "required": ["name", "offers"],
+        "recommended": ["description", "image", "sku", "brand", "aggregateRating"],
+    },
+    "Organization": {
+        "required": ["name", "url"],
+        "recommended": ["logo", "sameAs", "contactPoint", "description", "foundingDate"],
+    },
+    "LocalBusiness": {
+        "required": ["name", "address"],
+        "recommended": ["telephone", "openingHoursSpecification", "geo", "priceRange", "image", "url"],
+    },
+    "BreadcrumbList": {
+        "required": ["itemListElement"],
+        "recommended": [],
+    },
+    "VideoObject": {
+        "required": ["name", "description", "thumbnailUrl", "uploadDate"],
+        "recommended": ["duration", "contentUrl", "embedUrl", "interactionStatistic", "hasPart"],
+    },
+    "WebSite": {
+        "required": ["url"],
+        "recommended": ["name", "potentialAction"],
+    },
+    "Event": {
+        "required": ["name", "startDate", "location"],
+        "recommended": ["endDate", "description", "image", "organizer", "offers"],
+    },
+    "Recipe": {
+        "required": ["name", "image", "author", "datePublished"],
+        "recommended": ["description", "cookTime", "prepTime", "totalTime", "recipeYield",
+                        "recipeIngredient", "recipeInstructions", "aggregateRating"],
+    },
+}
+
+KNOWN_TYPES = set(SCHEMA_RULES.keys())
+
+
+# ─── HTML Parser to extract JSON-LD blocks ───────────────────────────────────
+
+class JSONLDExtractor(HTMLParser):
+    """Extracts all <script type="application/ld+json"> blocks from HTML."""
+
+    def __init__(self):
+        super().__init__()
+        self.blocks: List[str] = []
+        self._in_ld_json = False
+        self._current = []
+
+    def handle_starttag(self, tag: str, attrs: list):
+        if tag.lower() == "script":
+            attr_dict = dict(attrs)
+            if attr_dict.get("type", "").lower() == "application/ld+json":
+                self._in_ld_json = True
+                self._current = []
+
+    def handle_endtag(self, tag: str):
+        if tag.lower() == "script" and self._in_ld_json:
+            self._in_ld_json = False
+            self.blocks.append("".join(self._current).strip())
+
+    def handle_data(self, data: str):
+        if self._in_ld_json:
+            self._current.append(data)
+
+
+# ─── Validation logic ────────────────────────────────────────────────────────
+
+def detect_type(obj: Dict) -> Optional[str]:
+    """Determine the @type of a schema object."""
+    t = obj.get("@type")
+    if isinstance(t, list):
+        # Return first known type
+        for item in t:
+            if item in KNOWN_TYPES:
+                return item
+        return t[0] if t else None
+    return t
+
+
+def score_schema(schema_type: str, obj: Dict) -> Dict:
+    """Score a single schema object against known rules. Returns 0-100."""
+    if schema_type not in SCHEMA_RULES:
+        return {
+            "score": 50,
+            "status": "unknown_type",
+            "required_present": [],
+            "required_missing": [],
+            "recommended_present": [],
+            "recommended_missing": [],
+            "notes": [f"No validation rules defined for '{schema_type}' — manual check recommended."],
+        }
+
+    rules = SCHEMA_RULES[schema_type]
+    required = rules.get("required", [])
+    recommended = rules.get("recommended", [])
+
+    required_present = [f for f in required if f in obj and obj[f]]
+    required_missing = [f for f in required if f not in obj or not obj[f]]
+    recommended_present = [f for f in recommended if f in obj and obj[f]]
+    recommended_missing = [f for f in recommended if f not in obj or not obj[f]]
+
+    # Score: required fields = 70 points, recommended = 30 points
+    req_score = (len(required_present) / len(required) * 70) if required else 70
+    rec_score = (len(recommended_present) / len(recommended) * 30) if recommended else 30
+    total_score = int(req_score + rec_score)
+
+    notes = []
+
+    # Type-specific checks
+    if schema_type in ("Article", "BlogPosting", "NewsArticle"):
+        image = obj.get("image")
+        if image:
+            img_url = image if isinstance(image, str) else image.get("url", "") if isinstance(image, dict) else ""
+            if img_url and not img_url.startswith("http"):
+                notes.append("⚠️  'image' URL appears to be relative — must be absolute (https://...)")
+        if "datePublished" in obj:
+            dp = obj["datePublished"]
+            if not re.match(r"\d{4}-\d{2}-\d{2}", str(dp)):
+                notes.append("⚠️  'datePublished' should be ISO 8601 format: YYYY-MM-DD")
+
+    if schema_type == "Product":
+        offers = obj.get("offers", {})
+        if isinstance(offers, dict):
+            price = offers.get("price")
+            if isinstance(price, str) and any(c in price for c in "$€£¥"):
+                notes.append("⚠️  'offers.price' should be numeric (49.99), not a string with currency symbol.")
+            avail = offers.get("availability", "")
+            if avail and not avail.startswith("https://schema.org/"):
+                notes.append("⚠️  'offers.availability' must use full URL: https://schema.org/InStock")
+
+    if schema_type == "FAQPage":
+        entities = obj.get("mainEntity", [])
+        if isinstance(entities, list):
+            for i, q in enumerate(entities):
+                if not q.get("acceptedAnswer", {}).get("text"):
+                    notes.append(f"⚠️  Question #{i+1} has empty 'acceptedAnswer.text'")
+
+    if schema_type == "BreadcrumbList":
+        items = obj.get("itemListElement", [])
+        if isinstance(items, list):
+            positions = [item.get("position") for item in items if isinstance(item, dict)]
+            if sorted(positions) != list(range(1, len(positions) + 1)):
+                notes.append("⚠️  'itemListElement' positions must be sequential integers starting at 1.")
+
+    return {
+        "score": total_score,
+        "status": "valid" if not required_missing else "missing_required",
+        "required_present": required_present,
+        "required_missing": required_missing,
+        "recommended_present": recommended_present,
+        "recommended_missing": recommended_missing,
+        "notes": notes,
+    }
+
+
+def validate_block(raw_json: str, block_index: int) -> List[Dict]:
+    """Parse and validate a single JSON-LD block. Returns list of results (may contain @graph)."""
+    results = []
+    try:
+        data = json.loads(raw_json)
+    except json.JSONDecodeError as e:
+        return [{
+            "block": block_index,
+            "type": "PARSE_ERROR",
+            "score": 0,
+            "status": "parse_error",
+            "error": str(e),
+            "notes": ["❌ JSON is malformed — fix syntax before validation."],
+        }]
+
+    # Handle @graph
+    objects = data.get("@graph", [data]) if isinstance(data, dict) else [data]
+
+    for obj in objects:
+        if not isinstance(obj, dict):
+            continue
+        schema_type = detect_type(obj)
+        if not schema_type:
+            results.append({
+                "block": block_index,
+                "type": "UNKNOWN",
+                "score": 0,
+                "status": "no_type",
+                "notes": ["❌ No '@type' found in schema object."],
+            })
+            continue
+
+        validation = score_schema(schema_type, obj)
+        results.append({
+            "block": block_index,
+            "type": schema_type,
+            **validation,
+        })
+
+    return results
+
+
+def grade(score: int) -> str:
+    if score >= 90:
+        return "🟢 Excellent"
+    if score >= 70:
+        return "🟡 Good"
+    if score >= 50:
+        return "🟠 Needs Work"
+    return "🔴 Poor"
+
+
+# ─── Report printer ──────────────────────────────────────────────────────────
+
+def print_report(all_results: List[Dict], html_source: str) -> None:
+    print("\n" + "═" * 60)
+    print("  SCHEMA MARKUP VALIDATION REPORT")
+    print("═" * 60)
+
+    if not all_results:
+        print("\n❌ No JSON-LD blocks found in this HTML.")
+        print("   Add structured data in <script type=\"application/ld+json\"> tags.\n")
+        return
+
+    total_score = 0
+    for r in all_results:
+        print(f"\n── Block {r['block']} · @type: {r['type']} ──")
+        score = r.get("score", 0)
+        total_score += score
+        print(f"   Score: {score}/100  {grade(score)}")
+
+        if r.get("status") == "parse_error":
+            print(f"   ❌ Parse error: {r.get('error')}")
+            continue
+
+        if r.get("required_missing"):
+            print(f"   Missing required: {', '.join(r['required_missing'])}")
+        else:
+            print(f"   Required fields: ✅ All present ({', '.join(r.get('required_present', []))})")
+
+        if r.get("recommended_missing"):
+            print(f"   Missing recommended: {', '.join(r['recommended_missing'])}")
+        if r.get("recommended_present"):
+            print(f"   Recommended present: {', '.join(r['recommended_present'])}")
+
+        for note in r.get("notes", []):
+            print(f"   {note}")
+
+    avg = total_score // len(all_results) if all_results else 0
+    print(f"\n{'═' * 60}")
+    print(f"  OVERALL SCORE: {avg}/100  {grade(avg)}")
+    print(f"  Blocks analyzed: {len(all_results)}")
+    print("═" * 60)
+
+    print("\n📋 TESTING CHECKLIST")
+    print("  □ Google Rich Results Test: https://search.google.com/test/rich-results")
+    print("  □ Schema.org Validator: https://validator.schema.org")
+    print("  □ After deploy: Check Search Console → Enhancements\n")
+
+
+# ─── Sample HTML ─────────────────────────────────────────────────────────────
+
+SAMPLE_HTML = """<!DOCTYPE html>
+<html>
+<head>
+  <title>How to Write Cold Emails That Get Replies</title>
+
+  <!-- Article schema — headline present, but image is relative URL -->
+  <script type="application/ld+json">
+  {
+    "@context": "https://schema.org",
+    "@type": "BlogPosting",
+    "headline": "How to Write Cold Emails That Get Replies",
+    "image": "/images/cold-email-guide.jpg",
+    "datePublished": "2024-03-01",
+    "dateModified": "2024-03-15",
+    "author": {
+      "@type": "Person",
+      "name": "Reza Rezvani"
+    },
+    "publisher": {
+      "@type": "Organization",
+      "name": "Growth Lab",
+      "logo": {
+        "@type": "ImageObject",
+        "url": "https://growthlab.com/logo.png"
+      }
+    }
+  }
+  </script>
+
+  <!-- FAQPage schema — complete and valid -->
+  <script type="application/ld+json">
+  {
+    "@context": "https://schema.org",
+    "@type": "FAQPage",
+    "mainEntity": [
+      {
+        "@type": "Question",
+        "name": "What is the ideal length for a cold email?",
+        "acceptedAnswer": {
+          "@type": "Answer",
+          "text": "Keep cold emails under 150 words. Busy professionals scan, not read. If your email needs scrolling, it will not get a reply."
+        }
+      },
+      {
+        "@type": "Question",
+        "name": "How many follow-ups should I send?",
+        "acceptedAnswer": {
+          "@type": "Answer",
+          "text": "Send 3-5 follow-ups with increasing gaps (3 days, 5 days, 7 days, 14 days). Each follow-up must add new value — never just check in."
+        }
+      }
+    ]
+  }
+  </script>
+
+  <!-- BreadcrumbList — position gap (jumps from 1 to 3) -->
+  <script type="application/ld+json">
+  {
+    "@context": "https://schema.org",
+    "@type": "BreadcrumbList",
+    "itemListElement": [
+      {
+        "@type": "ListItem",
+        "position": 1,
+        "name": "Home",
+        "item": "https://growthlab.com"
+      },
+      {
+        "@type": "ListItem",
+        "position": 3,
+        "name": "How to Write Cold Emails",
+        "item": "https://growthlab.com/blog/cold-email-guide"
+      }
+    ]
+  }
+  </script>
+
+</head>
+<body>
+  <h1>How to Write Cold Emails That Get Replies</h1>
+  <p>Cold email works when it sounds human...</p>
+</body>
+</html>
+"""
+
+
+# ─── Main ─────────────────────────────────────────────────────────────────────
+
+def main():
+    import argparse
+
+    parser = argparse.ArgumentParser(
+        description="Extracts and validates JSON-LD structured data from HTML. "
+                    "Scores 0-100 per schema block based on required/recommended field coverage."
+    )
+    parser.add_argument(
+        "file", nargs="?", default=None,
+        help="Path to an HTML file to validate. "
+             "Use '-' to read from stdin. If omitted, runs embedded sample."
+    )
+    args = parser.parse_args()
+
+    if args.file:
+        if args.file == "-":
+            html = sys.stdin.read()
+        else:
+            try:
+                with open(args.file, "r", encoding="utf-8") as f:
+                    html = f.read()
+            except FileNotFoundError:
+                print(f"Error: File not found: {args.file}", file=sys.stderr)
+                sys.exit(1)
+    else:
+        print("No file provided — running on embedded sample HTML.\n")
+        html = SAMPLE_HTML
+
+    extractor = JSONLDExtractor()
+    extractor.feed(html)
+
+    all_results = []
+    for i, block in enumerate(extractor.blocks, start=1):
+        results = validate_block(block, i)
+        all_results.extend(results)
+
+    print_report(all_results, html)
+
+    # JSON output for programmatic use
+    summary = {
+        "blocks_found": len(extractor.blocks),
+        "schemas_validated": len(all_results),
+        "average_score": (sum(r.get("score", 0) for r in all_results) // len(all_results)) if all_results else 0,
+        "results": all_results,
+    }
+    print("\n── JSON Output ──")
+    print(json.dumps(summary, indent=2))
+
+
+if __name__ == "__main__":
+    main()

package/skills/scope-check/SKILL.md

@@ -0,0 +1,67 @@
+---
+name: scope-check
+description: "Analyze feature or sprint for scope creep: compare current vs original plan, flag additions, quantify bloat, recommend cuts."
+category: "workflow"
+argument-hint: "[feature-name or sprint-N]"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash
+model: haiku
+---
+
+# Scope Check
+
+This skill is read-only — it reports findings but writes no files.
+
+Compares original planned scope against current state to detect, quantify, and triage
+scope creep.
+
+**Argument:** `$ARGUMENTS[0]` — feature name, sprint number, or milestone name.
+
+---
+
+## Phase 1: Find the Original Plan
+
+Locate the baseline scope document for the given argument:
+
+- **Feature name** -> read `design/gdd/[feature].md` or matching file in `design/`
+- **Sprint number** (e.g., `sprint-3`) -> read `production/sprints/sprint-03.md` or similar
+- **Milestone** -> read `production/milestones/[name].md`
+
+If the document is not found, report the missing file and stop. Do not proceed without
+a baseline to compare against.
+
+---
+
+## Phase 2: Read the Current State
+
+Check what has actually been implemented or is in progress:
+
+- Scan the codebase for files related to the feature/sprint
+- Read git log for commits related to this work (`git log --oneline --since=[start-date]`)
+- Check for TODO/FIXME comments that indicate unfinished scope additions
+- Check active sprint plan if the feature is mid-sprint
+
+---
+
+## Phase 3: Compare Original vs Current Scope
+
+> → Read references/report-template.md for full comparison report template, verdict table, and scoring rules
+
+---
+
+## Phase 4: Verdict
+
+Assign a canonical verdict based on net scope change (<=10% PASS, 10-25% CONCERNS, >25% FAIL). Output the verdict prominently.
+
+---
+
+## Phase 5: Next Steps
+
+After presenting the report, offer concrete follow-up:
+
+- **PASS** -> no action required. Suggest re-running before next milestone.
+- **CONCERNS** -> offer to identify the 2-3 additions with best cut ratio. Reference `/sprint-plan update` to formally re-scope.
+- **FAIL** -> recommend escalating to producer. Reference `/sprint-plan update` for re-planning or `/estimate` to re-baseline timeline.
+
+Always end with:
+> "Run `/scope-check [name]` again after cuts are made to verify the verdict improves."

package/skills/scope-check/references/report-template.md

@@ -0,0 +1,56 @@
+# Scope Check Report Template
+
+```markdown
+## Scope Check: [Feature/Sprint Name]
+Generated: [Date]
+
+### Original Scope
+[List of items from the original plan]
+
+### Current Scope
+[List of items currently implemented or in progress]
+
+### Scope Additions (not in original plan)
+| Addition | Source | When | Justified? | Effort |
+|----------|--------|------|------------|--------|
+| [item] | [commit/person] | [date] | [Yes/No/Unclear] | [S/M/L] |
+
+### Scope Removals (in original but dropped)
+| Removed Item | Reason | Impact |
+|-------------|--------|--------|
+| [item] | [why removed] | [what's affected] |
+
+### Bloat Score
+- Original items: [N]
+- Current items: [N]
+- Items added: [N] (+[X]%)
+- Items removed: [N]
+- Net scope change: [+/-N] ([X]%)
+
+### Risk Assessment
+- **Schedule Risk**: [Low/Medium/High] — [explanation]
+- **Quality Risk**: [Low/Medium/High] — [explanation]
+- **Integration Risk**: [Low/Medium/High] — [explanation]
+
+### Recommendations
+1. **Cut**: [Items that should be removed to stay on schedule]
+2. **Defer**: [Items that can move to a future sprint/version]
+3. **Keep**: [Additions that are genuinely necessary]
+4. **Flag**: [Items that need a decision from producer/creative-director]
+```
+
+## Verdict Table
+
+| Net Change | Verdict | Meaning |
+|-----------|---------|---------|
+| <=10% | **PASS** | On Track — within acceptable variance |
+| 10-25% | **CONCERNS** | Minor Creep — manageable with targeted cuts |
+| 25-50% | **FAIL** | Significant Creep — must cut or formally extend timeline |
+| >50% | **FAIL** | Out of Control — stop, re-plan, escalate to producer |
+
+## Rules
+
+- Scope creep is additions without corresponding cuts or timeline extensions
+- Not all additions are bad — some are discovered requirements. But they must be acknowledged and accounted for
+- When recommending cuts, prioritize preserving the core player experience over nice-to-haves
+- Always quantify scope changes — "it feels bigger" is not actionable, "+35% items" is

package/skills/scrum-master/SKILL.md

@@ -0,0 +1,128 @@
+---
+name: scrum-master
+description: "Data-driven Scrum Master for sprint analytics, Monte Carlo forecasting, multi-dimension health scoring, and retrospective action-item tracking using Python analysis scripts."
+argument-hint: ""
+category: "agile"
+user-invocable: true
+allowed-tools: Read, Glob, Grep, Bash
+---
+
+# Scrum Master Expert
+
+Data-driven Scrum Master skill combining sprint analytics, probabilistic forecasting, and team development coaching. The unique value is in the three Python analysis scripts and their workflows.
+
+## Analysis Tools & Usage
+
+### 1. Velocity Analyzer (`scripts/velocity_analyzer.py`)
+
+Rolling averages, linear-regression trend detection, and Monte Carlo simulation over sprint history.
+
+```bash
+python velocity_analyzer.py sprint_data.json --format text   # Text report
+python velocity_analyzer.py sprint_data.json --format json   # JSON output
+```
+
+**Outputs**: velocity trend, coefficient of variation, 6-sprint Monte Carlo forecast at 50/70/85/95% confidence intervals, anomaly flags.
+
+**Validation**: If fewer than 3 sprints, stop and prompt. 6+ sprints recommended for statistically significant results.
+
+### 2. Sprint Health Scorer (`scripts/sprint_health_scorer.py`)
+
+Scores team health across 6 weighted dimensions (0-100 grade):
+
+| Dimension | Weight | Target |
+|---|---|---|
+| Commitment Reliability | 25% | >85% sprint goals met |
+| Scope Stability | 20% | <15% mid-sprint changes |
+| Blocker Resolution | 15% | <3 days average |
+| Ceremony Engagement | 15% | >90% participation |
+| Story Completion Distribution | 15% | High ratio of fully done stories |
+| Velocity Predictability | 10% | CV <20% |
+
+```bash
+python sprint_health_scorer.py sprint_data.json --format text
+```
+
+**Validation**: Requires 2+ sprints. Report missing dimensions and ask user to supply gaps.
+
+### 3. Retrospective Analyzer (`scripts/retrospective_analyzer.py`)
+
+Tracks action-item completion, recurring themes, sentiment trends, and team maturity progression.
+
+```bash
+python retrospective_analyzer.py sprint_data.json --format text
+```
+
+**Outputs**: Action-item completion rate, recurring-theme persistence, team maturity level (forming/storming/norming/performing), improvement-velocity trend.
+
+**Validation**: Requires 3+ retrospectives. With fewer, offer partial theme analysis only.
+
+## Input Requirements
+
+All scripts accept JSON following the schema in `assets/sample_sprint_data.json`. Jira and similar tools can export sprint data; map exported fields to this schema before running.
+
+## Sprint Execution Workflows
+
+### Sprint Planning
+1. Run velocity analysis; use 70% confidence interval as recommended commitment ceiling
+2. Review health scorer's Commitment Reliability and Scope Stability to calibrate negotiation
+3. If CV >20%, surface range estimates rather than single-point forecasts
+4. Document capacity assumptions for retrospective comparison
+
+### Daily Standup
+1. Track participation and help-seeking patterns for ceremony data
+2. Log each blocker with date opened; resolution time feeds Blocker Resolution dimension
+3. If blocker unresolved after 2 days, escalate proactively
+
+### Sprint Review
+1. Present velocity trend and health score alongside demo for stakeholder context
+2. Capture scope-change requests raised during review
+
+### Sprint Retrospective
+1. Run all three scripts before the session
+2. Open with health score and top-flagged dimensions to focus discussion
+3. Use action-item completion rate to determine how many new items the team can absorb (target: 3 or fewer if completion rate <60%)
+4. Assign each action item an owner and measurable success criterion
+5. Record new action items in sprint data for tracking in next cycle
+
+## Team Development
+
+### Assessment
+Run health scorer and retrospective analyzer. Map maturity output to development stage. Supplement with psychological safety pulse survey.
+
+### Intervention
+
+> See references/team-dynamics-framework.md for stage-specific facilitation details.
+
+| Stage | Focus |
+|---|---|
+| Forming | Structure, process education, trust building |
+| Storming | Conflict facilitation, psychological safety |
+| Norming | Autonomy building, process ownership transfer |
+| Performing | Challenge introduction, innovation support |
+
+### Progress Measurement
+- Sprint cadence: re-run health scorer; target +5 points per quarter
+- Monthly: psychological safety pulse; target >4.0/5.0
+- Quarterly: full maturity re-assessment
+- If plateau for 2 consecutive sprints, escalate intervention strategy
+
+## Key Metrics & Targets
+
+| Metric | Target |
+|---|---|
+| Overall Health Score | >80/100 |
+| Psychological Safety Index | >4.0/5.0 |
+| Velocity CV | <20% |
+| Commitment Reliability | >85% |
+| Scope Stability | <15% mid-sprint changes |
+| Blocker Resolution Time | <3 days |
+| Ceremony Engagement | >90% |
+| Retro Action Completion | >70% |
+
+## Limitations
+
+- Fewer than 6 sprints reduces Monte Carlo confidence -- always state confidence intervals
+- Missing ceremony/story data suppresses affected scoring dimensions
+- Metrics do not replace qualitative observation; combine with direct team interaction
+- Techniques optimized for 5-9 member teams; larger groups may require adaptation