cli-jaw 0.1.0

package/skills_ref/speech/SKILL.md

@@ -0,0 +1,144 @@
+---
+name: "speech"
+description: "Use when the user asks for text-to-speech narration or voiceover, accessibility reads, audio prompts, or batch speech generation via the OpenAI Audio API; run the bundled CLI (`scripts/text_to_speech.py`) with built-in voices and require `OPENAI_API_KEY` for live calls. Custom voice creation is out of scope."
+---
+
+
+# Speech Generation Skill
+
+Generate spoken audio for the current project (narration, product demo voiceover, IVR prompts, accessibility reads). Defaults to `gpt-4o-mini-tts-2025-12-15` and built-in voices, and prefers the bundled CLI for deterministic, reproducible runs.
+
+## When to use
+- Generate a single spoken clip from text
+- Generate a batch of prompts (many lines, many files)
+
+## Decision tree (single vs batch)
+- If the user provides multiple lines/prompts or wants many outputs -> **batch**
+- Else -> **single**
+
+## Workflow
+1. Decide intent: single vs batch (see decision tree above).
+2. Collect inputs up front: exact text (verbatim), desired voice, delivery style, format, and any constraints.
+3. If batch: write a temporary JSONL under tmp/ (one job per line), run once, then delete the JSONL.
+4. Augment instructions into a short labeled spec without rewriting the input text.
+5. Run the bundled CLI (`scripts/text_to_speech.py`) with sensible defaults (see references/cli.md).
+6. For important clips, validate: intelligibility, pacing, pronunciation, and adherence to constraints.
+7. Iterate with a single targeted change (voice, speed, or instructions), then re-check.
+8. Save/return final outputs and note the final text + instructions + flags used.
+
+## Temp and output conventions
+- Use `tmp/speech/` for intermediate files (for example JSONL batches); delete when done.
+- Write final artifacts under `output/speech/` when working in this repo.
+- Use `--out` or `--out-dir` to control output paths; keep filenames stable and descriptive.
+
+## Dependencies (install if missing)
+Prefer `uv` for dependency management.
+
+Python packages:
+```
+uv pip install openai
+```
+If `uv` is unavailable:
+```
+python3 -m pip install openai
+```
+
+## Environment
+- `OPENAI_API_KEY` must be set for live API calls.
+
+If the key is missing, give the user these steps:
+1. Create an API key in the OpenAI platform UI: https://platform.openai.com/api-keys
+2. Set `OPENAI_API_KEY` as an environment variable in their system.
+3. Offer to guide them through setting the environment variable for their OS/shell if needed.
+- Never ask the user to paste the full key in chat. Ask them to set it locally and confirm when ready.
+
+If installation isn't possible in this environment, tell the user which dependency is missing and how to install it locally.
+
+## Defaults & rules
+- Use `gpt-4o-mini-tts-2025-12-15` unless the user requests another model.
+- Default voice: `cedar`. If the user wants a brighter tone, prefer `marin`.
+- Built-in voices only. Custom voices are out of scope for this skill.
+- `instructions` are supported for GPT-4o mini TTS models, but not for `tts-1` or `tts-1-hd`.
+- Input length must be <= 4096 characters per request. Split longer text into chunks.
+- Enforce 50 requests/minute. The CLI caps `--rpm` at 50.
+- Require `OPENAI_API_KEY` before any live API call.
+- Provide a clear disclosure to end users that the voice is AI-generated.
+- Use the OpenAI Python SDK (`openai` package) for all API calls; do not use raw HTTP.
+- Prefer the bundled CLI (`scripts/text_to_speech.py`) over writing new one-off scripts.
+- Never modify `scripts/text_to_speech.py`. If something is missing, ask the user before doing anything else.
+
+## Instruction augmentation
+Reformat user direction into a short, labeled spec. Only make implicit details explicit; do not invent new requirements.
+
+Quick clarification (augmentation vs invention):
+- If the user says "narration for a demo", you may add implied delivery constraints (clear, steady pacing, friendly tone).
+- Do not introduce a new persona, accent, or emotional style the user did not request.
+
+Template (include only relevant lines):
+```
+Voice Affect: <overall character and texture of the voice>
+Tone: <attitude, formality, warmth>
+Pacing: <slow, steady, brisk>
+Emotion: <key emotions to convey>
+Pronunciation: <words to enunciate or emphasize>
+Pauses: <where to add intentional pauses>
+Emphasis: <key words or phrases to stress>
+Delivery: <cadence or rhythm notes>
+```
+
+Augmentation rules:
+- Keep it short; add only details the user already implied or provided elsewhere.
+- Do not rewrite the input text.
+- If any critical detail is missing and blocks success, ask a question; otherwise proceed.
+
+## Examples
+
+### Single example (narration)
+```
+Input text: "Welcome to the demo. Today we'll show how it works."
+Instructions:
+Voice Affect: Warm and composed.
+Tone: Friendly and confident.
+Pacing: Steady and moderate.
+Emphasis: Stress "demo" and "show".
+```
+
+### Batch example (IVR prompts)
+```
+{"input":"Thank you for calling. Please hold.","voice":"cedar","response_format":"mp3","out":"hold.mp3"}
+{"input":"For sales, press 1. For support, press 2.","voice":"marin","instructions":"Tone: Clear and neutral. Pacing: Slow.","response_format":"wav"}
+```
+
+## Instructioning best practices (short list)
+- Structure directions as: affect -> tone -> pacing -> emotion -> pronunciation/pauses -> emphasis.
+- Keep 4 to 8 short lines; avoid conflicting guidance.
+- For names/acronyms, add pronunciation hints (e.g., "enunciate A-I") or supply a phonetic spelling in the text.
+- For edits/iterations, repeat invariants (e.g., "keep pacing steady") to reduce drift.
+- Iterate with single-change follow-ups.
+
+More principles: `references/prompting.md`. Copy/paste specs: `references/sample-prompts.md`.
+
+## Guidance by use case
+Use these modules when the request is for a specific delivery style. They provide targeted defaults and templates.
+- Narration / explainer: `references/narration.md`
+- Product demo / voiceover: `references/voiceover.md`
+- IVR / phone prompts: `references/ivr.md`
+- Accessibility reads: `references/accessibility.md`
+
+## CLI + environment notes
+- CLI commands + examples: `references/cli.md`
+- API parameter quick reference: `references/audio-api.md`
+- Instruction patterns + examples: `references/voice-directions.md`
+- If network approvals / sandbox settings are getting in the way: `references/codex-network.md`
+
+## Reference map
+- **`references/cli.md`**: how to run speech generation/batches via `scripts/text_to_speech.py` (commands, flags, recipes).
+- **`references/audio-api.md`**: API parameters, limits, voice list.
+- **`references/voice-directions.md`**: instruction patterns and examples.
+- **`references/prompting.md`**: instruction best practices (structure, constraints, iteration patterns).
+- **`references/sample-prompts.md`**: copy/paste instruction recipes (examples only; no extra theory).
+- **`references/narration.md`**: templates + defaults for narration and explainers.
+- **`references/voiceover.md`**: templates + defaults for product demo voiceovers.
+- **`references/ivr.md`**: templates + defaults for IVR/phone prompts.
+- **`references/accessibility.md`**: templates + defaults for accessibility reads.
+- **`references/codex-network.md`**: environment/sandbox/network-approval troubleshooting.

package/skills_ref/spotify-player/SKILL.md

@@ -0,0 +1,64 @@
+---
+name: spotify-player
+description: Terminal Spotify playback/search via spogo (preferred) or spotify_player.
+homepage: https://www.spotify.com
+metadata:
+  {
+    "openclaw":
+      {
+        "emoji": "🎵",
+        "requires": { "anyBins": ["spogo", "spotify_player"] },
+        "install":
+          [
+            {
+              "id": "brew",
+              "kind": "brew",
+              "formula": "spogo",
+              "tap": "steipete/tap",
+              "bins": ["spogo"],
+              "label": "Install spogo (brew)",
+            },
+            {
+              "id": "brew",
+              "kind": "brew",
+              "formula": "spotify_player",
+              "bins": ["spotify_player"],
+              "label": "Install spotify_player (brew)",
+            },
+          ],
+      },
+  }
+---
+
+# spogo / spotify_player
+
+Use `spogo` **(preferred)** for Spotify playback/search. Fall back to `spotify_player` if needed.
+
+Requirements
+
+- Spotify Premium account.
+- Either `spogo` or `spotify_player` installed.
+
+spogo setup
+
+- Import cookies: `spogo auth import --browser chrome`
+
+Common CLI commands
+
+- Search: `spogo search track "query"`
+- Playback: `spogo play|pause|next|prev`
+- Devices: `spogo device list`, `spogo device set "<name|id>"`
+- Status: `spogo status`
+
+spotify_player commands (fallback)
+
+- Search: `spotify_player search "query"`
+- Playback: `spotify_player playback play|pause|next|previous`
+- Connect device: `spotify_player connect`
+- Like track: `spotify_player like`
+
+Notes
+
+- Config folder: `~/.config/spotify-player` (e.g., `app.toml`).
+- For Spotify Connect integration, set a user `client_id` in config.
+- TUI shortcuts are available via `?` in the app.

package/skills_ref/static-analysis/.claude-plugin/plugin.json

@@ -0,0 +1,8 @@
+{
+  "name": "static-analysis",
+  "version": "1.1.0",
+  "description": "Static analysis toolkit with CodeQL, Semgrep, and SARIF parsing for security vulnerability detection",
+  "author": {
+    "name": "Axel Mierczuk & Paweł Płatek"
+  }
+}

package/skills_ref/static-analysis/README.md

@@ -0,0 +1,65 @@
+# Static Analysis
+
+A comprehensive static analysis toolkit with CodeQL, Semgrep, and SARIF parsing for security vulnerability detection.
+
+CodeQL and Semgrep skills are based on the Trail of Bits Testing Handbook:
+
+- [CodeQL Testing Handbook](https://appsec.guide/docs/static-analysis/codeql/)
+- [Semgrep Testing Handbook](https://appsec.guide/docs/static-analysis/semgrep/)
+
+**Author:** Axel Mierczuk & Paweł Płatek
+
+## Skills Included
+
+| Skill           | Purpose                                                  |
+|-----------------|----------------------------------------------------------|
+| `codeql`        | Deep security analysis with taint tracking and data flow |
+| `semgrep`       | Fast pattern-based security scanning                     |
+| `sarif-parsing` | Parse and process results from static analysis tools     |
+
+## When to Use
+
+Use this plugin when you need to:
+- Perform security vulnerability detection on codebases
+- Run CodeQL for interprocedural taint tracking and data flow analysis
+- Use Semgrep for fast pattern-based bug detection
+- Parse SARIF output from security scanners
+- Aggregate and deduplicate findings from multiple tools
+
+## What It Does
+
+### CodeQL
+- Create databases for Python, JavaScript, Go, Java, C/C++, and more
+- Run security queries with SARIF/CSV output
+- Generate data extension models for project-specific APIs
+- Select and combine query packs (security-extended, Trail of Bits, Community)
+
+### Semgrep
+- Quick security scans using built-in rulesets (OWASP, CWE, Trail of Bits)
+- Write custom YAML rules with pattern matching
+- Taint mode for tracking data flow from sources to sinks
+- CI/CD integration with baseline scanning
+
+### SARIF Parsing
+- Understand SARIF 2.1.0 structure
+- Quick analysis using jq for CLI queries
+- Python scripting with pysarif and sarif-tools
+- Aggregate and deduplicate results from multiple files
+- CI/CD integration patterns
+
+## Agents Included
+
+| Agent              | Tools                  | Purpose                                                        |
+|--------------------|------------------------|----------------------------------------------------------------|
+| `semgrep-scanner`  | Bash                   | Executes parallel semgrep scans for a language category        |
+| `semgrep-triager`  | Read, Grep, Glob, Write | Classifies findings as true/false positives by reading source |
+
+## Installation
+
+```
+/plugin install trailofbits/skills/plugins/static-analysis
+```
+
+## Related Skills
+
+- `variant-analysis` - Use CodeQL/Semgrep patterns to find bug variants

package/skills_ref/static-analysis/agents/semgrep-scanner.md

@@ -0,0 +1,71 @@
+---
+name: semgrep-scanner
+description: "Executes semgrep CLI scans for a language category. Use when running automated static analysis scans with semgrep against a codebase."
+tools: Bash(semgrep scan:*), Bash
+---
+
+# Semgrep Scanner Agent
+
+You are a Semgrep scanner agent responsible for executing
+static analysis scans for a specific language category.
+
+## Core Rules
+
+1. **Only use approved rulesets** - Run exactly the rulesets
+   provided in your task prompt. Never add or remove rulesets.
+2. **Always use `--metrics=off`** - Prevents sending telemetry
+   to Semgrep servers. No exceptions.
+3. **Use `--pro` when available** - If the task indicates Pro
+   engine is available, always include the `--pro` flag for
+   cross-file taint tracking.
+4. **Parallel execution** - Run all rulesets simultaneously
+   using `&` and `wait`. Never run rulesets sequentially.
+
+## Scan Command Pattern
+
+For each approved ruleset, generate and run:
+
+```bash
+semgrep [--pro if available] \
+  --metrics=off \
+  --config [RULESET] \
+  --json -o [OUTPUT_DIR]/[lang]-[ruleset-name].json \
+  --sarif-output=[OUTPUT_DIR]/[lang]-[ruleset-name].sarif \
+  [TARGET] &
+```
+
+After launching all rulesets:
+
+```bash
+wait
+```
+
+## GitHub URL Rulesets
+
+For rulesets specified as GitHub URLs (e.g.,
+`https://github.com/trailofbits/semgrep-rules`):
+- Clone the repository first if not already cached locally
+- Use the local path as the `--config` value, or pass the
+  URL directly to semgrep (it handles GitHub URLs natively)
+
+## Output Requirements
+
+After all scans complete, report:
+- Number of findings per ruleset
+- Any scan errors or warnings
+- File paths of all generated JSON and SARIF results
+- If Pro was used, note any cross-file findings detected
+
+## Error Handling
+
+- If a ruleset fails to download, report the error but
+  continue with remaining rulesets
+- If semgrep exits non-zero for a scan, capture stderr and
+  include in report
+- Never silently skip a failed ruleset
+
+## Full Reference
+
+For the complete scanner task prompt template with variable
+substitutions and examples, see:
+`{baseDir}/skills/semgrep/references/scanner-task-prompt.md`

package/skills_ref/static-analysis/agents/semgrep-triager.md

@@ -0,0 +1,107 @@
+---
+name: semgrep-triager
+description: "Classifies semgrep scan findings as true or false positives by reading source context. Use when triaging static analysis results to separate real vulnerabilities from noise."
+tools: Read, Grep, Glob, Write
+---
+
+# Semgrep Triage Agent
+
+You are a security finding triager responsible for classifying
+Semgrep scan results as true or false positives by reading
+source code context.
+
+## Task
+
+For each finding in the provided JSON result files:
+
+1. Read the JSON finding (rule ID, file, line number)
+2. Read source code context (at least 5 lines before/after)
+3. Classify as `TRUE_POSITIVE` or `FALSE_POSITIVE`
+4. Write a brief reason for the classification
+
+## Decision Tree
+
+Apply these checks in order. The first match determines
+the classification:
+
+```
+Finding
+  |-- In a test file?
+  |     -> FALSE_POSITIVE (note: add to .semgrepignore)
+  |-- In example/documentation code?
+  |     -> FALSE_POSITIVE
+  |-- Has nosemgrep comment?
+  |     -> FALSE_POSITIVE (already acknowledged)
+  |-- Input sanitized/validated upstream?
+  |     Check 10-20 lines before for validation
+  |     -> FALSE_POSITIVE if validated
+  |-- Code path reachable?
+  |     Check if function is called/exported
+  |     -> FALSE_POSITIVE if dead code
+  |-- None of the above
+        -> TRUE_POSITIVE
+```
+
+## Classification Guidelines
+
+**TRUE_POSITIVE indicators:**
+- User input flows to sensitive sink without sanitization
+- Hardcoded credentials or API keys in source (not test) code
+- Known-vulnerable function usage in production paths
+- Missing security controls (no CSRF, no auth check)
+
+**FALSE_POSITIVE indicators:**
+- Test files with mock/fixture data
+- Input is validated before reaching the flagged line
+- Code is behind a feature flag or compile-time guard
+- Dead code (unreachable function, commented-out caller)
+- Documentation or example snippets
+
+## Output Format
+
+Write a triage file to `[OUTPUT_DIR]/[lang]-triage.json`:
+
+```json
+{
+  "file": "[lang]-[ruleset].json",
+  "total": 45,
+  "true_positives": [
+    {
+      "rule": "rule.id.here",
+      "file": "path/to/file.py",
+      "line": 42,
+      "reason": "User input in raw SQL without parameterization"
+    }
+  ],
+  "false_positives": [
+    {
+      "rule": "rule.id.here",
+      "file": "tests/test_file.py",
+      "line": 15,
+      "reason": "Test file with mock data"
+    }
+  ]
+}
+```
+
+## Report
+
+After triage, provide a summary:
+- Total findings examined
+- True positives count
+- False positives count with breakdown by reason category
+  (test files, sanitized inputs, dead code, etc.)
+
+## Important
+
+- Read actual source code for every finding. Never classify
+  based solely on the rule name or file path.
+- When uncertain, classify as TRUE_POSITIVE. False negatives
+  are worse than false positives in security triage.
+- Process all input JSON files for the language category.
+
+## Full Reference
+
+For the complete triage task prompt template with variable
+substitutions and examples, see:
+`{baseDir}/skills/semgrep/references/triage-task-prompt.md`

package/skills_ref/static-analysis/skills/codeql/SKILL.md

@@ -0,0 +1,119 @@
+---
+name: codeql
+description: >-
+  Runs CodeQL static analysis for security vulnerability detection
+  using interprocedural data flow and taint tracking. Applicable when
+  finding vulnerabilities, running a security scan, performing a security
+  audit, running CodeQL, building a CodeQL database, selecting query
+  rulesets, creating data extension models, or processing CodeQL SARIF
+  output. NOT for writing custom QL queries or CI/CD pipeline setup.
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Glob
+  - Grep
+  - AskUserQuestion
+  - Task
+  - TaskCreate
+  - TaskList
+  - TaskUpdate
+---
+
+# CodeQL Analysis
+
+Supported languages: Python, JavaScript/TypeScript, Go, Java/Kotlin, C/C++, C#, Ruby, Swift.
+
+**Skill resources:** Reference files and templates are located at `{baseDir}/references/` and `{baseDir}/workflows/`. Use `{baseDir}` to resolve paths to these files at runtime.
+
+## Quick Start
+
+For the common case ("scan this codebase for vulnerabilities"):
+
+```bash
+# 1. Verify CodeQL is installed
+command -v codeql >/dev/null 2>&1 && codeql --version || echo "NOT INSTALLED"
+
+# 2. Check for existing database
+ls -dt codeql_*.db 2>/dev/null | head -1
+```
+
+Then execute the full pipeline: **build database → create data extensions → run analysis** using the workflows below.
+
+## When to Use
+
+- Scanning a codebase for security vulnerabilities with deep data flow analysis
+- Building a CodeQL database from source code (with build capability for compiled languages)
+- Finding complex vulnerabilities that require interprocedural taint tracking or AST/CFG analysis
+- Performing comprehensive security audits with multiple query packs
+
+## When NOT to Use
+
+- **Writing custom queries** - Use a dedicated query development skill
+- **CI/CD integration** - Use GitHub Actions documentation directly
+- **Quick pattern searches** - Use Semgrep or grep for speed
+- **No build capability** for compiled languages - Consider Semgrep instead
+- **Single-file or lightweight analysis** - Semgrep is faster for simple pattern matching
+
+## Rationalizations to Reject
+
+These shortcuts lead to missed findings. Do not accept them:
+
+- **"security-extended is enough"** - It is the baseline. Always check if Trail of Bits packs and Community Packs are available for the language. They catch categories `security-extended` misses entirely.
+- **"The database built, so it's good"** - A database that builds does not mean it extracted well. Always run Step 4 (quality assessment) and check file counts against expected source files. A cached build produces zero useful extraction.
+- **"Data extensions aren't needed for standard frameworks"** - Even Django/Spring apps have custom wrappers around ORM calls, request parsing, or shell execution that CodeQL does not model. Skipping the extensions workflow means missing vulnerabilities in project-specific code.
+- **"build-mode=none is fine for compiled languages"** - It produces severely incomplete analysis. No interprocedural data flow through compiled code is traced. Only use as an absolute last resort and clearly flag the limitation.
+- **"No findings means the code is secure"** - Zero findings can indicate poor database quality, missing models, or wrong query packs. Investigate before reporting clean results.
+- **"I'll just run the default suite"** - The default suite varies by how CodeQL is invoked. Always explicitly specify the suite (e.g., `security-extended`) so results are reproducible.
+
+---
+
+## Workflow Selection
+
+This skill has three workflows:
+
+| Workflow | Purpose |
+|----------|---------|
+| [build-database](workflows/build-database.md) | Create CodeQL database using 3 build methods in sequence |
+| [create-data-extensions](workflows/create-data-extensions.md) | Detect or generate data extension models for project APIs |
+| [run-analysis](workflows/run-analysis.md) | Select rulesets, execute queries, process results |
+
+
+### Auto-Detection Logic
+
+**If user explicitly specifies** what to do (e.g., "build a database", "run analysis"), execute that workflow.
+
+**Default pipeline for "test", "scan", "analyze", or similar:** Execute all three workflows sequentially: build → extensions → analysis. The create-data-extensions step is critical for finding vulnerabilities in projects with custom frameworks or annotations that CodeQL doesn't model by default.
+
+```bash
+# Check if database exists
+DB=$(ls -dt codeql_*.db 2>/dev/null | head -1)
+if [ -n "$DB" ] && codeql resolve database -- "$DB" >/dev/null 2>&1; then
+  echo "DATABASE EXISTS ($DB) - can run analysis"
+else
+  echo "NO DATABASE - need to build first"
+fi
+```
+
+| Condition | Action |
+|-----------|--------|
+| No database exists | Execute build → extensions → analysis (full pipeline) |
+| Database exists, no extensions | Execute extensions → analysis |
+| Database exists, extensions exist | Ask user: run analysis on existing DB, or rebuild? |
+| User says "just run analysis" or "skip extensions" | Run analysis only |
+
+
+### Decision Prompt
+
+If unclear, ask user:
+
+```
+I can help with CodeQL analysis. What would you like to do?
+
+1. **Full scan (Recommended)** - Build database, create extensions, then run analysis
+2. **Build database** - Create a new CodeQL database from this codebase
+3. **Create data extensions** - Generate custom source/sink models for project APIs
+4. **Run analysis** - Run security queries on existing database
+
+[If database exists: "I found an existing database at <DB_NAME>"]
+```