@mohanscodex/spectra-code 0.4.9 → 0.5.0

package/skills/transcribe/scripts/transcribe_diarize.py

@@ -0,0 +1,276 @@
+#!/usr/bin/env python3
+"""Transcribe audio (optionally with speaker diarization) using OpenAI."""
+
+from __future__ import annotations
+
+import argparse
+import base64
+import json
+import mimetypes
+import os
+from pathlib import Path
+import sys
+from typing import Any, Dict, List, Optional, Tuple
+
+DEFAULT_MODEL = "gpt-4o-mini-transcribe"
+DEFAULT_RESPONSE_FORMAT = "text"
+DEFAULT_CHUNKING_STRATEGY = "auto"
+MAX_AUDIO_BYTES = 25 * 1024 * 1024
+MAX_KNOWN_SPEAKERS = 4
+
+ALLOWED_RESPONSE_FORMATS = {"text", "json", "diarized_json"}
+
+
+def _die(message: str, code: int = 1) -> None:
+    print(f"Error: {message}", file=sys.stderr)
+    raise SystemExit(code)
+
+
+def _warn(message: str) -> None:
+    print(f"Warning: {message}", file=sys.stderr)
+
+
+def _ensure_api_key(dry_run: bool) -> None:
+    if os.getenv("OPENAI_API_KEY"):
+        print("OPENAI_API_KEY is set.", file=sys.stderr)
+        return
+    if dry_run:
+        _warn("OPENAI_API_KEY is not set; dry-run only.")
+        return
+    _die("OPENAI_API_KEY is not set. Export it before running.")
+
+
+def _normalize_response_format(value: Optional[str]) -> str:
+    if not value:
+        return DEFAULT_RESPONSE_FORMAT
+    fmt = value.strip().lower()
+    if fmt not in ALLOWED_RESPONSE_FORMATS:
+        _die(
+            "response-format must be one of: "
+            + ", ".join(sorted(ALLOWED_RESPONSE_FORMATS))
+        )
+    return fmt
+
+
+def _normalize_chunking_strategy(value: Optional[str]) -> Any:
+    if not value:
+        return DEFAULT_CHUNKING_STRATEGY
+    raw = str(value).strip()
+    if raw.startswith("{"):
+        try:
+            return json.loads(raw)
+        except json.JSONDecodeError:
+            _die("chunking-strategy JSON is invalid")
+    return raw
+
+
+def _guess_mime_type(path: Path) -> str:
+    mime, _ = mimetypes.guess_type(str(path))
+    if mime:
+        return mime
+    return "audio/wav"
+
+
+def _encode_data_url(path: Path) -> str:
+    data = path.read_bytes()
+    mime = _guess_mime_type(path)
+    encoded = base64.b64encode(data).decode("ascii")
+    return f"data:{mime};base64,{encoded}"
+
+
+def _parse_known_speakers(raw_items: List[str]) -> Tuple[List[str], List[str]]:
+    names: List[str] = []
+    refs: List[str] = []
+    for raw in raw_items:
+        if "=" not in raw:
+            _die("known-speaker must be NAME=PATH")
+        name, path_str = raw.split("=", 1)
+        name = name.strip()
+        path = Path(path_str.strip())
+        if not name or not path_str.strip():
+            _die("known-speaker must be NAME=PATH")
+        if not path.exists():
+            _die(f"Known speaker file not found: {path}")
+        names.append(name)
+        refs.append(_encode_data_url(path))
+    if len(names) > MAX_KNOWN_SPEAKERS:
+        _die(f"known speakers must be <= {MAX_KNOWN_SPEAKERS}")
+    return names, refs
+
+
+def _output_extension(response_format: str) -> str:
+    return "txt" if response_format == "text" else "json"
+
+
+def _build_output_path(
+    audio_path: Path,
+    response_format: str,
+    out: Optional[str],
+    out_dir: Optional[str],
+) -> Path:
+    ext = "." + _output_extension(response_format)
+    if out:
+        path = Path(out)
+        if path.exists() and path.is_dir():
+            return path / f"{audio_path.stem}.transcript{ext}"
+        if path.suffix == "":
+            return path.with_suffix(ext)
+        return path
+    if out_dir:
+        base = Path(out_dir)
+        base.mkdir(parents=True, exist_ok=True)
+        return base / f"{audio_path.stem}.transcript{ext}"
+    return Path(f"{audio_path.stem}.transcript{ext}")
+
+
+def _create_client():
+    try:
+        from openai import OpenAI
+    except ImportError:
+        _die("openai SDK not installed. Install with `uv pip install openai`.")
+    return OpenAI()
+
+
+def _format_output(result: Any, response_format: str) -> str:
+    if response_format == "text":
+        text = getattr(result, "text", None)
+        return text if isinstance(text, str) else str(result)
+    if hasattr(result, "model_dump"):
+        return json.dumps(result.model_dump(), indent=2)
+    if isinstance(result, (dict, list)):
+        return json.dumps(result, indent=2)
+    return json.dumps({"text": getattr(result, "text", str(result))}, indent=2)
+
+
+def _validate_audio(path: Path) -> None:
+    if not path.exists():
+        _die(f"Audio file not found: {path}")
+    size = path.stat().st_size
+    if size > MAX_AUDIO_BYTES:
+        _warn(
+            f"Audio file exceeds 25MB limit ({size} bytes): {path}"
+        )
+
+
+def _build_payload(
+    args: argparse.Namespace,
+    known_speaker_names: List[str],
+    known_speaker_refs: List[str],
+) -> Dict[str, Any]:
+    payload: Dict[str, Any] = {
+        "model": args.model,
+        "response_format": args.response_format,
+        "chunking_strategy": args.chunking_strategy,
+    }
+    if args.language:
+        payload["language"] = args.language
+    if args.prompt:
+        payload["prompt"] = args.prompt
+    if known_speaker_names:
+        payload["extra_body"] = {
+            "known_speaker_names": known_speaker_names,
+            "known_speaker_references": known_speaker_refs,
+        }
+    return payload
+
+
+def _run_one(
+    client: Any,
+    audio_path: Path,
+    payload: Dict[str, Any],
+) -> Any:
+    with audio_path.open("rb") as audio_file:
+        return client.audio.transcriptions.create(
+            file=audio_file,
+            **payload,
+        )
+
+
+def main() -> None:
+    parser = argparse.ArgumentParser(
+        description="Transcribe audio (optionally with speaker diarization) using OpenAI."
+    )
+    parser.add_argument("audio", nargs="+", help="Audio file(s) to transcribe")
+    parser.add_argument(
+        "--model",
+        default=DEFAULT_MODEL,
+        help=f"Model to use (default: {DEFAULT_MODEL})",
+    )
+    parser.add_argument(
+        "--response-format",
+        default=DEFAULT_RESPONSE_FORMAT,
+        help="Response format: text, json, or diarized_json",
+    )
+    parser.add_argument(
+        "--chunking-strategy",
+        default=DEFAULT_CHUNKING_STRATEGY,
+        help="Chunking strategy (use 'auto' for long audio)",
+    )
+    parser.add_argument("--language", help="Optional language hint (e.g. 'en')")
+    parser.add_argument("--prompt", help="Optional prompt to guide transcription")
+    parser.add_argument(
+        "--known-speaker",
+        action="append",
+        default=[],
+        help="Known speaker reference as NAME=PATH (repeatable, max 4)",
+    )
+    parser.add_argument("--out", help="Output file path (single audio only)")
+    parser.add_argument("--out-dir", help="Output directory for transcripts")
+    parser.add_argument(
+        "--stdout",
+        action="store_true",
+        help="Write transcript to stdout instead of a file",
+    )
+    parser.add_argument(
+        "--dry-run",
+        action="store_true",
+        help="Validate inputs and print payload without calling the API",
+    )
+
+    args = parser.parse_args()
+    args.response_format = _normalize_response_format(args.response_format)
+    args.chunking_strategy = _normalize_chunking_strategy(args.chunking_strategy)
+
+    if args.out and len(args.audio) > 1:
+        _die("--out only supports a single audio file")
+    if args.stdout and (args.out or args.out_dir):
+        _die("--stdout cannot be combined with --out or --out-dir")
+    if args.stdout and len(args.audio) > 1:
+        _die("--stdout only supports a single audio file")
+
+    if args.prompt and "transcribe-diarize" in args.model:
+        _die("prompt is not supported with gpt-4o-transcribe-diarize")
+    if args.response_format == "diarized_json" and "transcribe-diarize" not in args.model:
+        _die("diarized_json requires gpt-4o-transcribe-diarize")
+
+    _ensure_api_key(args.dry_run)
+
+    audio_paths = [Path(p) for p in args.audio]
+    for path in audio_paths:
+        _validate_audio(path)
+
+    known_names, known_refs = _parse_known_speakers(args.known_speaker)
+    if known_names and "transcribe-diarize" not in args.model:
+        _warn("known-speaker references are only supported for gpt-4o-transcribe-diarize")
+    payload = _build_payload(args, known_names, known_refs)
+
+    if args.dry_run:
+        print(json.dumps(payload, indent=2))
+        return
+
+    client = _create_client()
+
+    for path in audio_paths:
+        result = _run_one(client, path, payload)
+        output = _format_output(result, args.response_format)
+        if args.stdout:
+            print(output)
+            continue
+        out_path = _build_output_path(path, args.response_format, args.out, args.out_dir)
+        out_path.parent.mkdir(parents=True, exist_ok=True)
+        out_path.write_text(output, encoding="utf-8")
+        print(f"Wrote {out_path}")
+
+
+if __name__ == "__main__":
+    main()

package/skills/using-skills/SKILL.md

@@ -0,0 +1,102 @@
+---
+name: Getting Started with Skills
+description: Skills wiki intro - mandatory workflows, search tool, brainstorming triggers
+when_to_use: when starting any conversation
+version: 4.0.2
+---
+
+# Getting Started with Skills
+
+## Critical Rules
+
+1. **Use Read tool before announcing skill usage.** The session-start hook does NOT read skills for you. Announcing without calling Read = lying.
+
+2. **Follow mandatory workflows.** Brainstorming before coding. Check for skills before ANY task.
+
+3. **Create TodoWrite todos for checklists.** Mental tracking = steps get skipped. Every time.
+
+
+## Mandatory Workflow: Before ANY Task
+
+**1. Check skills list** at session start, or run `find-skills [PATTERN]` to filter.
+
+**2. If relevant skill exists, YOU MUST use it:**
+
+- Use Read tool with full path: `${SUPERPOWERS_SKILLS_ROOT}/skills/category/skill-name/SKILL.md`
+- Read ENTIRE file, not just frontmatter
+- Announce: "I've read [Skill Name] skill and I'm using it to [purpose]"
+- Follow it exactly
+
+**Don't rationalize:**
+- "I remember this skill" - Skills evolve. Read the current version.
+- "Session-start showed it to me" - That was using-skills/SKILL.md only. Read the actual skill.
+- "This doesn't count as a task" - It counts. Find and read skills.
+
+**Why:** Skills document proven techniques that save time and prevent mistakes. Not using available skills means repeating solved problems and making known errors.
+
+If a skill for your task exists, you must use it or you will fail at your task.
+
+## Skills with Checklists
+
+If a skill has a checklist, YOU MUST create TodoWrite todos for EACH item.
+
+**Don't:**
+- Work through checklist mentally
+- Skip creating todos "to save time"
+- Batch multiple items into one todo
+- Mark complete without doing them
+
+**Why:** Checklists without TodoWrite tracking = steps get skipped. Every time. The overhead of TodoWrite is tiny compared to the cost of missing steps.
+
+**Examples:** skills/testing/test-driven-development/SKILL.md, skills/debugging/systematic-debugging/SKILL.md, skills/meta/writing-skills/SKILL.md
+
+## Announcing Skill Usage
+
+After you've read a skill with Read tool, announce you're using it:
+
+"I've read the [Skill Name] skill and I'm using it to [what you're doing]."
+
+**Examples:**
+- "I've read the Brainstorming skill and I'm using it to refine your idea into a design."
+- "I've read the Test-Driven Development skill and I'm using it to implement this feature."
+- "I've read the Systematic Debugging skill and I'm using it to find the root cause."
+
+**Why:** Transparency helps your human partner understand your process and catch errors early. It also confirms you actually read the skill.
+
+## How to Read a Skill
+
+Every skill has the same structure:
+
+1. **Frontmatter** - `when_to_use` tells you if this skill matches your situation
+2. **Overview** - Core principle in 1-2 sentences
+3. **Quick Reference** - Scan for your specific pattern
+4. **Implementation** - Full details and examples
+5. **Supporting files** - Load only when implementing
+
+**Many skills contain rigid rules (TDD, debugging, verification).** Follow them exactly. Don't adapt away the discipline.
+
+**Some skills are flexible patterns (architecture, naming).** Adapt core principles to your context.
+
+The skill itself tells you which type it is.
+
+## Instructions ≠ Permission to Skip Workflows
+
+Your human partner's specific instructions describe WHAT to do, not HOW.
+
+"Add X", "Fix Y" = the goal, NOT permission to skip brainstorming, TDD, or RED-GREEN-REFACTOR.
+
+**Red flags:** "Instruction was specific" • "Seems simple" • "Workflow is overkill"
+
+**Why:** Specific instructions mean clear requirements, which is when workflows matter MOST. Skipping process on "simple" tasks is how simple tasks become complex problems.
+
+## Summary
+
+**Starting any task:**
+1. Run find-skills to check for relevant skills
+2. If relevant skill exists → Use Read tool with full path (includes /SKILL.md)
+3. Announce you're using it
+4. Follow what it says
+
+**Skill has checklist?** TodoWrite for every item.
+
+**Finding a relevant skill = mandatory to read and use it. Not optional.**

package/skills/using-skills/find-skills

@@ -0,0 +1,107 @@
+#!/usr/bin/env bash
+# find-skills - Find and list skills with when_to_use guidance
+# Shows all skills by default, filters by pattern if provided
+
+set -euo pipefail
+
+# Determine directories
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SKILLS_DIR="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+SUPERPOWERS_DIR="${XDG_CONFIG_HOME:-$HOME/.config}/superpowers"
+LOG_FILE="${SUPERPOWERS_DIR}/search-log.jsonl"
+
+# Show help
+if [[ "${1:-}" == "--help" ]] || [[ "${1:-}" == "-h" ]]; then
+    cat <<'EOF'
+find-skills - Find and list skills with when_to_use guidance
+
+USAGE:
+  find-skills              Show all skills with when_to_use guidance
+  find-skills PATTERN      Filter skills by grep pattern
+  find-skills --help       Show this help
+
+EXAMPLES:
+  find-skills                        # All skills
+  find-skills test                   # Skills matching "test"
+  find-skills 'test.*driven|TDD'     # Regex pattern
+
+OUTPUT:
+  Each line shows: Use skill-path/SKILL.md when [trigger]
+  Paths include /SKILL.md for direct use with Read tool
+
+SEARCH:
+  Searches both skill content AND path names.
+  Skills location: ~/.config/superpowers/skills/
+EOF
+    exit 0
+fi
+
+# Get pattern (optional)
+PATTERN="${1:-}"
+
+# Function to extract when_to_use from SKILL.md
+get_when_to_use() {
+    local file="$1"
+    grep "^when_to_use:" "$file" 2>/dev/null | head -1 | sed 's/when_to_use: *//' || echo ""
+}
+
+# Function to get relative skill path (includes /SKILL.md)
+get_skill_path() {
+    local file="$1"
+    local base_dir="$2"
+    local rel_path="${file#$base_dir/}"
+    echo "$rel_path"
+}
+
+# Collect all matching skills
+results=()
+
+# If pattern provided, log the search
+if [[ -n "$PATTERN" ]]; then
+    timestamp=$(date -u +"%Y-%m-%dT%H:%M:%SZ")
+    echo "{\"timestamp\":\"$timestamp\",\"query\":\"$PATTERN\"}" >> "$LOG_FILE" 2>/dev/null || true
+fi
+
+# Search skills directory
+while IFS= read -r file; do
+    [[ -z "$file" ]] && continue
+
+    skill_path=$(get_skill_path "$file" "$SKILLS_DIR")
+    when_to_use=$(get_when_to_use "$file")
+    results+=("$skill_path|$when_to_use")
+done < <(
+    if [[ -n "$PATTERN" ]]; then
+        # Pattern mode: search content and paths
+        {
+            grep -E -r -- "$PATTERN" "$SKILLS_DIR/" --include="SKILL.md" -l 2>/dev/null || true
+            find "$SKILLS_DIR/" -name "SKILL.md" -type f 2>/dev/null | grep -E -- "$PATTERN" 2>/dev/null || true
+        } | sort -u
+    else
+        # Show all
+        find "$SKILLS_DIR/" -name "SKILL.md" -type f 2>/dev/null || true
+    fi
+)
+
+# Check if we found anything
+if [[ ${#results[@]} -eq 0 ]]; then
+    if [[ -n "$PATTERN" ]]; then
+        echo "❌ No skills found matching: $PATTERN"
+        echo ""
+        echo "Search logged. If a skill should exist, consider writing it!"
+    else
+        echo "❌ No skills found"
+    fi
+    exit 0
+fi
+
+# Sort and display results
+printf "%s\n" "${results[@]}" | sort | while IFS='|' read -r skill_path when_to_use; do
+    if [[ -n "$when_to_use" ]]; then
+        echo "Use $skill_path $when_to_use"
+    else
+        echo "$skill_path"
+    fi
+done
+
+exit 0

package/skills/using-skills/skill-run

@@ -0,0 +1,44 @@
+#!/usr/bin/env bash
+# Generic runner for skill scripts
+#
+# Usage: scripts/skill-run <skill-relative-path> [args...]
+# Example: scripts/skill-run skills/collaboration/remembering-conversations/tool/search-conversations "query"
+
+set -euo pipefail
+
+if [[ $# -eq 0 ]]; then
+    cat <<'EOF'
+Usage: scripts/skill-run <skill-relative-path> [args...]
+
+Runs scripts from skills directory.
+
+Examples:
+  scripts/skill-run skills/collaboration/remembering-conversations/tool/search-conversations "query"
+  scripts/skill-run skills/collaboration/remembering-conversations/tool/index-conversations --cleanup
+
+The script will be found at:
+  ${SUPERPOWERS_SKILLS_ROOT}/<skill-relative-path>
+EOF
+    exit 1
+fi
+
+# Get the script path to run
+SCRIPT_PATH="$1"
+shift  # Remove script path from args, leaving remaining args
+
+# Determine directories
+SCRIPT_DIR="$(cd "$(dirname "${BASH_SOURCE[0]}")" && pwd)"
+SKILLS_ROOT="$(cd "$SCRIPT_DIR/../.." && pwd)"
+
+# Try to run the script
+SCRIPT="${SKILLS_ROOT}/${SCRIPT_PATH}"
+if [[ -x "$SCRIPT" ]]; then
+    exec "$SCRIPT" "$@"
+fi
+
+# Not found
+echo "Error: Script not found: $SCRIPT_PATH" >&2
+echo "" >&2
+echo "Searched:" >&2
+echo "  $SCRIPT" >&2
+exit 1

package/skills/vercel-deploy/LICENSE.txt

@@ -0,0 +1,21 @@
+MIT License
+
+Copyright (c) 2026 Vercel
+
+Permission is hereby granted, free of charge, to any person obtaining a copy
+of this software and associated documentation files (the "Software"), to deal
+in the Software without restriction, including without limitation the rights
+to use, copy, modify, merge, publish, distribute, sublicense, and/or sell
+copies of the Software, and to permit persons to whom the Software is
+furnished to do so, subject to the following conditions:
+
+The above copyright notice and this permission notice shall be included in all
+copies or substantial portions of the Software.
+
+THE SOFTWARE IS PROVIDED "AS IS", WITHOUT WARRANTY OF ANY KIND, EXPRESS OR
+IMPLIED, INCLUDING BUT NOT LIMITED TO THE WARRANTIES OF MERCHANTABILITY,
+FITNESS FOR A PARTICULAR PURPOSE AND NONINFRINGEMENT. IN NO EVENT SHALL THE
+AUTHORS OR COPYRIGHT HOLDERS BE LIABLE FOR ANY CLAIM, DAMAGES OR OTHER
+LIABILITY, WHETHER IN AN ACTION OF CONTRACT, TORT OR OTHERWISE, ARISING FROM,
+OUT OF OR IN CONNECTION WITH THE SOFTWARE OR THE USE OR OTHER DEALINGS IN THE
+SOFTWARE.

package/skills/vercel-deploy/SKILL.md

@@ -0,0 +1,77 @@
+---
+name: vercel-deploy
+description: Deploy applications and websites to Vercel. Use when the user requests deployment actions like "deploy my app", "deploy and give me the link", "push this live", or "create a preview deployment".
+---
+
+# Vercel Deploy
+
+Deploy any project to Vercel instantly. **Always deploy as preview** (not production) unless the user explicitly asks for production.
+
+## Prerequisites
+
+- Check whether the Vercel CLI is installed without changing runtime permissions (for example, `command -v vercel`).
+- Respect the current runtime permission and network policy. If deployment network calls are blocked, stop and report the blocker; ask the user to run in an environment where they have explicitly allowed Vercel network access.
+- The deployment might take a few minutes. Use appropriate timeout values.
+
+## Quick Start
+
+1. Check whether the Vercel CLI is installed (no escalation for this check):
+
+```bash
+command -v vercel
+```
+
+2. If `vercel` is installed, run this (with a 10 minute timeout):
+```bash
+vercel deploy [path] -y
+```
+
+**Important:** Use a 10 minute (600000ms) timeout for the deploy command since builds can take a while.
+
+3. If `vercel` is not installed, or if the CLI fails with "No existing credentials found", use the fallback method below.
+
+## Fallback (No Auth)
+
+If CLI fails with auth error, use the deploy script:
+
+```bash
+skill_dir="<path-to-skill>"
+
+# Deploy current directory
+bash "$skill_dir/scripts/deploy.sh"
+
+# Deploy specific project
+bash "$skill_dir/scripts/deploy.sh" /path/to/project
+
+# Deploy existing tarball
+bash "$skill_dir/scripts/deploy.sh" /path/to/project.tgz
+```
+
+The script handles framework detection, packaging, and deployment. It waits for the build to complete and returns JSON with `previewUrl` and `claimUrl`.
+
+**Tell the user:** "Your deployment is ready at [previewUrl]. Claim it at [claimUrl] to manage your deployment."
+
+## Production Deploys
+
+Only if user explicitly asks:
+```bash
+vercel deploy [path] --prod -y
+```
+
+## Output
+
+Show the user the deployment URL. For fallback deployments, also show the claim URL.
+
+**Do not** curl or fetch the deployed URL to verify it works. Just return the link.
+
+## Troubleshooting
+
+### Escalated Network Access
+
+If deployment fails due to network issues (timeouts, DNS errors, connection resets), first distinguish provider/network failure from runtime policy blocking. When runtime policy blocks outbound deployment calls, do not weaken the policy from inside the skill. Do not change policy for the `command -v vercel` installation check.
+
+Example guidance to the user:
+
+```
+The deploy needs Vercel network access, but the current runtime policy blocked it. Please approve network access or run this deploy from an environment where Vercel access is allowed.
+```

package/skills/vercel-deploy/agents/openai.yaml

@@ -0,0 +1,6 @@
+interface:
+  display_name: "Vercel Deploy"
+  short_description: "Deploy apps and agents with zero configuration on Vercel. No account required."
+  icon_small: "./assets/vercel-small.svg"
+  icon_large: "./assets/vercel.png"
+  default_prompt: "Create a Vercel deployment for this project and share the URL."

package/skills/vercel-deploy/assets/vercel-small.svg

@@ -0,0 +1,5 @@
+<svg width="16" height="16" viewBox="0 0 1155 1155" fill="none" xmlns="http://www.w3.org/2000/svg" aria-hidden="true">
+  <g transform="translate(0 77.5)">
+    <path fill="currentColor" d="M577.344 0L1154.69 1000H0L577.344 0Z" />
+  </g>
+</svg>