@diottodev/runic 1.0.0 → 1.1.0

package/engineering/claude-coach/skills/claude-coach/scripts/coach_tip_classifier.py

@@ -0,0 +1,205 @@
+#!/usr/bin/env python3
+"""
+coach_tip_classifier.py — decide whether the current turn warrants a power-user
+tip, using the 5-gate decision tree defined in references/coaching-rules.md.
+
+Gates (in order):
+  1. Tip already given on the previous turn? → silent
+  2. Prompt already well-formed (score >= 8 via prompt_rater)? → silent
+  3. Deep-work mode (long technical/creative/emotional context)? → silent
+  4. Tip would be obvious/condescending? → silent
+  5. Exactly one higher-impact path missed? → emit that one tip
+
+Stdlib-only. Heuristic-only — no LLM calls. Designed to be invoked by the
+claude-coach skill before composing a response.
+
+Usage:
+    python3 coach_tip_classifier.py --prompt "Can you help me with my email?"
+    python3 coach_tip_classifier.py --prompt "..." --previous-tip-given --json
+    python3 coach_tip_classifier.py --sample
+"""
+
+import argparse
+import json
+import re
+import sys
+from dataclasses import dataclass, field, asdict
+
+
+# Inlined minimal prompt scorer — keeps this script self-contained so the
+# security auditor does not flag cross-script imports as dynamic loads.
+# Mirrors the dimensions used by prompt_rater.py: clarity / constraint / format
+# / audience. Maximum score 10.
+_CLARITY_VERBS = ("write", "draft", "summarize", "review", "compare", "explain", "translate", "rewrite", "list", "rank", "score", "outline", "design", "debug", "refactor", "test")
+_LENGTH_TOKENS = (r"\b\d+\s*(words?|sentences?|paragraphs?|bullets?|lines?|pages?|tokens?)\b", r"one\s+(sentence|paragraph|line)", r"short", r"brief", r"detailed")
+_FORMAT_TOKENS = (r"\bmarkdown\b", r"\btable\b", r"\bjson\b", r"\byaml\b", r"\bcsv\b", r"\bbullet\b", r"\blist\b", r"\bcode\b", r"\bemail\b", r"\bmemo\b", r"\boutline\b")
+_AUDIENCE_TOKENS = (r"\bfor\s+(my|a|the)\s+[A-Za-z][A-Za-z\- ]+\b", r"\btargeting\s+\w+", r"\bnon-technical\b", r"\btechnical\b", r"\bexecutive\w*\b", r"\bjunior\b", r"\bsenior\b", r"\bteam\b", r"\bcustomer\w*\b", r"\bremote workers\b", r"you are\b", r"act as\b", r"as a\b")
+_CONSTRAINT_EXTRA = (r"\bno\s+(more|less)\s+than\b", r"\bmust\b", r"\bcannot\b", r"\bavoid\b", r"\bonly\b")
+
+
+def _has_any(text: str, patterns) -> bool:
+    return any(re.search(p, text, re.IGNORECASE) for p in patterns)
+
+
+def score_prompt(prompt: str) -> int:
+    p = prompt.strip()
+    verb_hits = min(sum(1 for v in _CLARITY_VERBS if re.search(rf"\b{v}\b", p, re.IGNORECASE)), 2)
+    ends_q = p.endswith("?")
+    word_count = len(p.split())
+    is_vague_open = ends_q and word_count < 8
+    clarity = max(0, min(3, verb_hits + (0 if is_vague_open else 1) + (1 if word_count >= 6 else 0)))
+    constraint = 2 if _has_any(p, _LENGTH_TOKENS) or _has_any(p, _CONSTRAINT_EXTRA) else 0
+    fmt = 2 if _has_any(p, _FORMAT_TOKENS) else 0
+    audience = 2 if _has_any(p, _AUDIENCE_TOKENS) else 0
+    return min(10, clarity + constraint + fmt + audience + (1 if word_count >= 12 else 0))
+
+DEEP_WORK_MARKERS = (
+    r"\bstack\s*trace\b",
+    r"\btraceback\b",
+    r"\bsegfault\b",
+    r"```",
+    r"\bworking on\b",
+    r"\bin the middle of\b",
+    r"\bfeeling\b",
+    r"\bvent(ing)?\b",
+    r"\bjust\s+(do|write|give)\b.*\bno\s+(commentary|extras|tips)\b",
+)
+SUPPRESS_MARKERS = (
+    r"\bstop\s+(with\s+)?the\s+tips\b",
+    r"\bno\s+coaching\b",
+    r"\bquiet mode\b",
+    r"\bdon[’']?t coach\b",
+)
+
+# Patterns that map to specific tips. Order matters — first match wins.
+TIP_RULES: list[tuple[re.Pattern[str], str, str]] = [
+    (re.compile(r"\bhelp me with my email\b|\bwrite (a |an )?email\b", re.IGNORECASE),
+     "Name the audience and the desired outcome upfront — that cuts two rounds of revision.",
+     'e.g. "Reply to my manager declining Friday\'s meeting, professional tone, suggest async update."'),
+    (re.compile(r"^thoughts\??$|\bany thoughts\b", re.IGNORECASE),
+     "Ask for thoughts on a specific dimension instead of an open take.",
+     'e.g. "What\'s the weakest claim and how would you attack it?"'),
+    (re.compile(r"\bcurrent\b|\blatest\b|\btoday\b|\bnews\b|\bprice\b|\bversion\b", re.IGNORECASE),
+     "For time-sensitive info, ask Claude to search the web — the knowledge cutoff bites here.",
+     'e.g. "Search the web for the current pricing on …"'),
+    (re.compile(r"\b(can|could) you (make|give|do|write)\b.*\b(better|nicer|cleaner)\b", re.IGNORECASE),
+     "Name the dimension instead of saying 'better'. Concrete = measurable.",
+     'e.g. "Cut 30%, remove every adjective, keep all numbers."'),
+    (re.compile(r"\b(list|table|json|markdown)\b", re.IGNORECASE),
+     "",
+     ""),  # Suppress — prompt already specifies output shape.
+]
+
+
+@dataclass
+class Decision:
+    prompt: str
+    coach: bool
+    reason: str
+    tip: str = ""
+    tip_example: str = ""
+    gates: dict[str, str] = field(default_factory=dict)
+
+
+def is_deep_work(prompt: str) -> bool:
+    return any(re.search(p, prompt, re.IGNORECASE) for p in DEEP_WORK_MARKERS) or len(prompt) > 800
+
+
+def is_suppression(prompt: str) -> bool:
+    return any(re.search(p, prompt, re.IGNORECASE) for p in SUPPRESS_MARKERS)
+
+
+def pick_tip(prompt: str) -> tuple[str, str]:
+    for pattern, tip, example in TIP_RULES:
+        if pattern.search(prompt):
+            return tip, example
+    return "", ""
+
+
+def classify(prompt: str, previous_tip_given: bool = False) -> Decision:
+    decision = Decision(prompt=prompt, coach=False, reason="")
+    decision.gates["1_previous_tip"] = "blocked" if previous_tip_given else "pass"
+    decision.gates["suppression"] = "blocked" if is_suppression(prompt) else "pass"
+
+    if previous_tip_given:
+        decision.reason = "Gate 1 — tip already given on the previous turn."
+        return decision
+    if is_suppression(prompt):
+        decision.reason = "Suppression marker present — user does not want coaching right now."
+        return decision
+
+    prompt_score = score_prompt(prompt)
+    decision.gates["2_prompt_score"] = f"{prompt_score}/10"
+    if prompt_score >= 8:
+        decision.reason = "Gate 2 — prompt already well-formed (score >= 8)."
+        return decision
+
+    decision.gates["3_deep_work"] = "blocked" if is_deep_work(prompt) else "pass"
+    if is_deep_work(prompt):
+        decision.reason = "Gate 3 — deep-work mode (long context, traceback, code block, or emotional content)."
+        return decision
+
+    tip, example = pick_tip(prompt)
+    decision.gates["4_specificity"] = "skip" if not tip else "pass"
+    if not tip:
+        decision.reason = "Gate 4/5 — no specific high-impact tip applies. Stay silent."
+        return decision
+
+    decision.coach = True
+    decision.reason = "All gates passed — emit one tip."
+    decision.tip = tip
+    decision.tip_example = example
+    decision.gates["5_single_high_impact"] = "pass"
+    return decision
+
+
+def render_human(d: Decision) -> str:
+    head = "COACH" if d.coach else "SILENT"
+    out = [f"[{head}] {d.reason}"]
+    if d.coach:
+        out.append(f"⚡ Power-user tip: {d.tip}")
+        if d.tip_example:
+            out.append(d.tip_example)
+    out.append(f"gates: {d.gates}")
+    return "\n".join(out)
+
+
+def sample_run() -> int:
+    cases = [
+        ("Can you help me with my email?", False),
+        ("Write a 200-word product description for a noise-cancelling headphone targeting remote workers, focused on the focus-time benefit, no marketing fluff.", False),
+        ("thoughts?", False),
+        ("Can you make this better?", True),
+        ("stop with the tips, just rewrite it", False),
+    ]
+    for prompt, prev in cases:
+        d = classify(prompt, previous_tip_given=prev)
+        print(render_human(d))
+        print("-" * 60)
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Classify whether the current turn warrants a coaching tip.")
+    parser.add_argument("--prompt", type=str, help="Prompt text to classify")
+    parser.add_argument("--previous-tip-given", action="store_true", help="Flag that a tip was already given on the previous turn")
+    parser.add_argument("--json", action="store_true", help="Emit JSON instead of human-readable text")
+    parser.add_argument("--sample", action="store_true", help="Run against a built-in set of sample prompts")
+    args = parser.parse_args(argv)
+
+    if args.sample:
+        return sample_run()
+
+    if not args.prompt:
+        parser.error("--prompt is required unless --sample is passed")
+
+    d = classify(args.prompt, previous_tip_given=args.previous_tip_given)
+    if args.json:
+        print(json.dumps(asdict(d), indent=2))
+    else:
+        print(render_human(d))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/engineering/claude-coach/skills/claude-coach/scripts/prompt_rater.py

@@ -0,0 +1,176 @@
+#!/usr/bin/env python3
+"""
+prompt_rater.py — score a user prompt 0-10 across four dimensions and emit a
+structured rating with a recommended rewrite.
+
+Dimensions:
+  - clarity      : is the ask unambiguous?
+  - constraint   : is there at least one measurable constraint (length, format, audience, deadline)?
+  - format       : is the desired output shape specified?
+  - audience     : is the reader/role named or implied?
+
+Stdlib-only. Heuristic-only — no LLM calls. The output is designed to be
+consumed by the claude-coach skill's "rate that prompt" flow.
+
+Usage:
+    python3 prompt_rater.py --prompt "Can you help me with my email?"
+    python3 prompt_rater.py --prompt "..." --json
+    python3 prompt_rater.py --sample
+"""
+
+import argparse
+import json
+import re
+import sys
+from dataclasses import dataclass, field, asdict
+
+CLARITY_VERBS = ("write", "draft", "summarize", "review", "compare", "explain", "translate", "rewrite", "list", "rank", "score", "outline", "design", "debug", "refactor", "test")
+LENGTH_TOKENS = (r"\b\d+\s*(words?|sentences?|paragraphs?|bullets?|lines?|pages?|tokens?)\b", r"one\s+(sentence|paragraph|line)", r"short", r"brief", r"detailed")
+FORMAT_TOKENS = (r"\bmarkdown\b", r"\btable\b", r"\bjson\b", r"\byaml\b", r"\bcsv\b", r"\bbullet\b", r"\blist\b", r"\bcode\b", r"\bemail\b", r"\bmemo\b", r"\boutline\b")
+AUDIENCE_TOKENS = (r"\bfor\s+(my|a|the)\s+[A-Za-z][A-Za-z\- ]+\b", r"\btargeting\s+\w+", r"\bnon-technical\b", r"\btechnical\b", r"\bexecutive\w*\b", r"\bjunior\b", r"\bsenior\b", r"\bteam\b", r"\bcustomer\w*\b", r"\bremote workers\b")
+ROLE_TOKENS = (r"you are\b", r"act as\b", r"as a\b")
+
+
+@dataclass
+class Rating:
+    prompt: str
+    clarity: int = 0
+    constraint: int = 0
+    fmt: int = 0
+    audience: int = 0
+    score: int = 0
+    what_worked: str = ""
+    what_to_improve: str = ""
+    better_version: str = ""
+    breakdown: dict[str, str] = field(default_factory=dict)
+
+
+def _has_any(text: str, patterns) -> bool:
+    return any(re.search(p, text, re.IGNORECASE) for p in patterns)
+
+
+def _verb_strength(text: str) -> int:
+    hits = sum(1 for v in CLARITY_VERBS if re.search(rf"\b{v}\b", text, re.IGNORECASE))
+    return min(hits, 2)
+
+
+def rate(prompt: str) -> Rating:
+    p = prompt.strip()
+    rating = Rating(prompt=p)
+
+    verb_score = _verb_strength(p)
+    length_ok = _has_any(p, LENGTH_TOKENS)
+    ends_with_question = p.endswith("?")
+    is_vague_open = ends_with_question and len(p.split()) < 8
+
+    rating.clarity = max(0, min(3, verb_score + (0 if is_vague_open else 1) + (1 if len(p.split()) >= 6 else 0)))
+    rating.constraint = 2 if length_ok or _has_any(p, (r"\bno\s+(more|less)\s+than\b", r"\bmust\b", r"\bcannot\b", r"\bavoid\b", r"\bonly\b")) else 0
+    rating.fmt = 2 if _has_any(p, FORMAT_TOKENS) else 0
+    rating.audience = 2 if (_has_any(p, AUDIENCE_TOKENS) or _has_any(p, ROLE_TOKENS)) else 0
+
+    raw = rating.clarity + rating.constraint + rating.fmt + rating.audience
+    rating.score = min(10, raw + (1 if len(p.split()) >= 12 else 0))
+
+    rating.breakdown = {
+        "clarity": f"{rating.clarity}/3",
+        "constraint": f"{rating.constraint}/2",
+        "format": f"{rating.fmt}/2",
+        "audience": f"{rating.audience}/2",
+        "length_bonus": "+1" if len(p.split()) >= 12 else "+0",
+    }
+
+    if rating.score >= 8:
+        rating.what_worked = "Specific action verb, named constraint, and clear audience."
+        rating.what_to_improve = "Already well-formed. Optionally request a self-critique pass after the first draft."
+        rating.better_version = p
+    elif rating.score >= 5:
+        worked = []
+        if rating.clarity >= 2:
+            worked.append("clear action")
+        if rating.constraint:
+            worked.append("named constraint")
+        if rating.fmt:
+            worked.append("output format specified")
+        if rating.audience:
+            worked.append("audience implied")
+        rating.what_worked = ", ".join(worked) or "concrete enough to act on"
+        if not rating.audience:
+            rating.what_to_improve = "Name the audience or role explicitly."
+        elif not rating.constraint:
+            rating.what_to_improve = "Add a measurable constraint (e.g. word count, must-include, must-avoid)."
+        elif not rating.fmt:
+            rating.what_to_improve = "Specify the output shape (markdown table, JSON, bullets, prose)."
+        else:
+            rating.what_to_improve = "Tighten with one more constraint to cut iteration."
+        rating.better_version = _augment(p, rating)
+    else:
+        rating.what_worked = "There is a topic to anchor on."
+        rating.what_to_improve = "Replace the open question with a concrete ask: action verb + length + audience + format."
+        rating.better_version = _augment(p, rating, aggressive=True)
+
+    return rating
+
+
+def _augment(prompt: str, rating: Rating, aggressive: bool = False) -> str:
+    additions: list[str] = []
+    if not rating.constraint:
+        additions.append("in 200 words")
+    if not rating.audience:
+        additions.append("for a non-technical reader")
+    if not rating.fmt:
+        additions.append("as markdown bullets")
+    if not additions:
+        return prompt
+    base = prompt.rstrip(" .?")
+    suffix = ", ".join(additions)
+    if aggressive and not any(v in prompt.lower() for v in CLARITY_VERBS):
+        base = f"Write a focused response to: {base}"
+    return f"{base}, {suffix}."
+
+
+def render_human(r: Rating) -> str:
+    return (
+        f"**Their prompt:** {r.prompt}\n"
+        f"**Score:** {r.score}/10  ({r.breakdown})\n"
+        f"**What worked:** {r.what_worked}\n"
+        f"**What to improve:** {r.what_to_improve}\n"
+        f"**Better version:** {r.better_version}"
+    )
+
+
+def sample_run() -> int:
+    samples = [
+        "Can you help me with my email?",
+        "Write a 200-word product description for a noise-cancelling headphone targeting remote workers, focused on the focus-time benefit, no marketing fluff.",
+        "thoughts?",
+    ]
+    for s in samples:
+        r = rate(s)
+        print(render_human(r))
+        print("-" * 60)
+    return 0
+
+
+def main(argv: list[str] | None = None) -> int:
+    parser = argparse.ArgumentParser(description="Score a prompt 0-10 and emit a structured rating.")
+    parser.add_argument("--prompt", type=str, help="Prompt text to rate")
+    parser.add_argument("--json", action="store_true", help="Emit JSON instead of human-readable text")
+    parser.add_argument("--sample", action="store_true", help="Run against a built-in set of sample prompts")
+    args = parser.parse_args(argv)
+
+    if args.sample:
+        return sample_run()
+
+    if not args.prompt:
+        parser.error("--prompt is required unless --sample is passed")
+
+    r = rate(args.prompt)
+    if args.json:
+        print(json.dumps(asdict(r), indent=2))
+    else:
+        print(render_human(r))
+    return 0
+
+
+if __name__ == "__main__":
+    sys.exit(main())

package/engineering/code-review/SKILL.md

@@ -0,0 +1,116 @@
+---
+name: code-review
+description: "Performs a detailed code review highlighting bugs, security vulnerabilities, performance issues, and improvement suggestions with severity levels. Trigger: 'review', 'check', 'audit', 'is this good?', 'what's wrong here?', 'PR review'"
+---
+
+You are a senior software engineer with expertise in code quality, security, and performance. Your goal is to surface real problems that would matter in production — not just style preferences.
+
+## Context Detection
+
+Before reviewing, check for:
+- `package.json` / `pyproject.toml` — language, framework, and dependencies
+- Existing linting config (`.eslintrc`, `ruff.toml`, `.golangci.yml`)
+- Test files — to understand what's already covered
+- CI config — to know what gates already exist
+
+## When to Use This Skill
+
+**Use this skill when:** The user asks to review, check, or audit code — a function, file, module, or diff.
+
+**Don't use this skill when:** The user wants a *refactor* (code works, they want it cleaner) → use `refactor` skill instead.
+
+**Don't use this skill when:** The user has an error → use `debug-error` skill instead.
+
+## Modes
+
+### Mode 1 — Full Review (default)
+Comprehensive analysis across all categories: security, correctness, performance, maintainability.
+
+### Mode 2 — Focused Review
+User specifies: `security`, `performance`, `readability`, or `correctness`. Narrow analysis to that category only.
+
+### Mode 3 — PR Diff Review
+User provides a diff. Focus on what changed, not the full codebase. Flag regressions and breaking changes.
+
+## How to Perform the Review
+
+### 1. Quick Summary
+One paragraph: what does this code do, and what is the overall quality?
+
+### 2. Findings
+
+For each issue found:
+
+> **[SEVERITY] Category — Title**
+> - **Problem:** clear description
+> - **Fix:** concrete corrected code
+
+Severity levels:
+- 🔴 **Critical** — bugs, security holes, data loss risk
+- 🟡 **Warning** — edge case failures, performance issues, bad patterns
+- 🟢 **Suggestion** — readability, naming, style
+
+### 3. Categories
+
+**Security**
+- Injection (SQL, command, XSS, path traversal)
+- Exposed secrets, tokens, PII
+- Improper auth/authz
+- Unsafe deserialization
+
+**Correctness**
+- Logic bugs, off-by-one errors
+- Unhandled nulls, empty inputs, overflow
+- Race conditions, async timing errors
+- Wrong API usage
+
+**Performance**
+- O(n²) hidden in nested loops
+- Redundant computation in hot paths
+- Memory leaks, excessive allocations
+- N+1 queries
+
+**Maintainability**
+- Functions with more than one responsibility
+- Magic numbers, unexplained constants
+- Nesting > 3 levels
+- Misleading names
+
+### 4. Executive Summary
+
+- **Score:** X/10
+- **Top 3 issues to fix first**
+- **Verdict:** Ready to merge / Needs changes / Major rework required
+
+## Proactive Triggers
+
+Surface these even when not explicitly asked:
+- Hardcoded credentials or API keys → flag as Critical immediately
+- SQL string concatenation → flag SQL injection risk
+- Missing input validation on public-facing functions → flag
+- Async functions without error handling → flag
+- Unhandled promise rejections → flag
+- `any` type in TypeScript → flag as maintainability risk
+
+## Output Artifacts
+
+| Request | Deliverable |
+|---------|-------------|
+| "review my code" | Full findings report with severity + score |
+| "security review" | Security-only report with OWASP references |
+| "is this PR ready?" | Diff analysis with merge/block recommendation |
+| "quick check" | Top 3 critical findings only |
+
+## Quality Loop
+
+Before presenting the review:
+1. Did I address root causes, not just symptoms?
+2. Is every finding actionable (concrete fix provided)?
+3. Did I flag security issues as Critical regardless of other findings?
+4. Is my score calibrated (10/10 = production-ready with tests)?
+
+## Related Skills
+
+- `debug-error` — use when there's an actual error, not just a review request
+- `refactor` — use when code works but needs restructuring
+- `generate-tests` — use after review to add missing test coverage

package/engineering/code-tour/.claude-plugin/plugin.json

@@ -0,0 +1,15 @@
+{
+  "name": "code-tour",
+  "description": "Create CodeTour .tour files \u2014 persona-targeted, step-by-step walkthroughs that link to real files and line numbers. Supports 10 developer personas (vibecoder, new joiner, architect, security reviewer, etc.), all CodeTour step types, and SMIG description formula.",
+  "version": "2.9.0",
+  "author": {
+    "name": "Alireza Rezvani",
+    "url": "https://alirezarezvani.com"
+  },
+  "homepage": "https://github.com/alirezarezvani/claude-skills/tree/main/engineering/code-tour",
+  "repository": "https://github.com/alirezarezvani/claude-skills",
+  "license": "MIT",
+  "skills": [
+    "./skills"
+  ]
+}

package/engineering/code-tour/evals.json

@@ -0,0 +1,32 @@
+[
+  {
+    "id": 1,
+    "prompt": "I just hired a junior dev who starts Monday. Can you create an onboarding tour for this repo so they can get oriented on their own?",
+    "expected_output": "Agent infers new-joiner persona, standard depth (9-13 steps). Produces .tours/new-joiner-onboarding.tour with verified paths/lines, SMIG descriptions, narrative arc starting with orientation directory step.",
+    "scenario_type": "happy_path"
+  },
+  {
+    "id": 2,
+    "prompt": "Give me a quick vibe check tour of this codebase — I just cloned it and want to understand the shape before diving in.",
+    "expected_output": "Agent infers vibecoder persona, quick depth (5-8 steps). Tour hits entry point and main modules only. File saved to .tours/vibecoder-overview.tour.",
+    "scenario_type": "happy_path"
+  },
+  {
+    "id": 3,
+    "prompt": "We had an outage last night because the payment webhook handler silently swallowed errors. Can you build an RCA tour tracing how webhooks flow through the system?",
+    "expected_output": "Agent infers rca-investigator persona, standard depth. Tour follows causality chain from webhook entry point through handler to error handling. Steps anchored to specific lines showing the fault path.",
+    "scenario_type": "happy_path"
+  },
+  {
+    "id": 4,
+    "prompt": "Create a tour for this repo.",
+    "expected_output": "Agent defaults to new-joiner persona at standard depth without asking clarifying questions. Produces a general-purpose onboarding tour.",
+    "scenario_type": "edge_case"
+  },
+  {
+    "id": 5,
+    "prompt": "Make an onboarding tour for this repo, but I want it to also cover the deployment pipeline and our monitoring setup in Grafana.",
+    "expected_output": "Agent includes deployment pipeline files as normal file+line steps. Uses URI step type for Grafana link if user provides URL, or skips with explanation. Does not hallucinate files.",
+    "scenario_type": "edge_case"
+  }
+]