cli-jaw 0.1.7 → 0.1.8

package/skills_ref/speech/SKILL.md

@@ -1,144 +0,0 @@
----
-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

@@ -1,64 +0,0 @@
----
-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

@@ -1,8 +0,0 @@
-{
-  "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

@@ -1,65 +0,0 @@
-# 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

@@ -1,71 +0,0 @@
----
-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

@@ -1,107 +0,0 @@
----
-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

@@ -1,119 +0,0 @@
----
-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>"]
-```