@vigolium/piolium 0.0.1

package/skills/semgrep/workflows/scan-workflow.md

@@ -0,0 +1,311 @@
+# Semgrep Scan Workflow
+
+Complete 5-step scan execution process. Read from start to finish and follow each step in order.
+
+## Task System Enforcement
+
+On invocation, create these tasks with dependencies:
+
+```
+TaskCreate: "Detect languages and Pro availability" (Step 1)
+TaskCreate: "Select scan mode and rulesets" (Step 2) - blockedBy: Step 1
+TaskCreate: "Present plan with rulesets, get approval" (Step 3) - blockedBy: Step 2
+TaskCreate: "Execute scans with approved rulesets and mode" (Step 4) - blockedBy: Step 3
+TaskCreate: "Merge results and report" (Step 5) - blockedBy: Step 4
+```
+
+### Mandatory Gate
+
+| Task | Gate Type | Cannot Proceed Until |
+|------|-----------|---------------------|
+| Step 3 | **HARD GATE** | User explicitly approves rulesets + plan |
+
+Mark Step 3 as `completed` ONLY after user says "yes", "proceed", "approved", or equivalent.
+
+---
+
+## Step 1: Resolve Output Directory, Detect Languages and Pro Availability
+
+> **Entry:** User has specified or confirmed the target directory.
+> **Exit:** `OUTPUT_DIR` resolved and created; language list with file counts produced; Pro availability determined.
+
+### Resolve Output Directory
+
+If the user specified an output directory in their prompt, use it as `OUTPUT_DIR`. Otherwise, auto-increment. In both cases, **always `mkdir -p`** to ensure the directory exists.
+
+```bash
+if [ -n "$USER_SPECIFIED_DIR" ]; then
+  OUTPUT_DIR="$USER_SPECIFIED_DIR"
+else
+  BASE="static_analysis_semgrep"
+  N=1
+  while [ -e "${BASE}_${N}" ]; do
+    N=$((N + 1))
+  done
+  OUTPUT_DIR="${BASE}_${N}"
+fi
+mkdir -p "$OUTPUT_DIR/raw" "$OUTPUT_DIR/results"
+echo "Output directory: $OUTPUT_DIR"
+```
+
+`$OUTPUT_DIR` is used by all subsequent steps. Pass its **absolute path** to scanner subagents. Scanners write raw output to `$OUTPUT_DIR/raw/`; merged/filtered results go to `$OUTPUT_DIR/results/`.
+
+**Detect Pro availability** (requires Bash):
+
+```bash
+if ! command -v semgrep >/dev/null 2>&1; then
+  echo "ERROR: semgrep is not installed. Install from https://semgrep.dev/docs/getting-started/"
+  exit 1
+fi
+semgrep --version
+semgrep --pro --validate --config p/default 2>/dev/null && echo "Pro: AVAILABLE" || echo "Pro: NOT AVAILABLE"
+```
+
+**Detect languages** using Glob (not Bash). Run these patterns against the target directory and count matches:
+
+`**/*.py`, `**/*.js`, `**/*.ts`, `**/*.tsx`, `**/*.jsx`, `**/*.go`, `**/*.rb`, `**/*.java`, `**/*.php`, `**/*.c`, `**/*.cpp`, `**/*.rs`, `**/Dockerfile`, `**/*.tf`
+
+Also check for framework markers: `package.json`, `pyproject.toml`, `Gemfile`, `go.mod`, `Cargo.toml`, `pom.xml`. Use Read to inspect these files for framework dependencies (e.g., read `package.json` to detect React, Express, Next.js; read `pyproject.toml` for Django, Flask, FastAPI).
+
+Map findings to categories:
+
+| Detection | Category |
+|-----------|----------|
+| `.py`, `pyproject.toml` | Python |
+| `.js`, `.ts`, `package.json` | JavaScript/TypeScript |
+| `.go`, `go.mod` | Go |
+| `.rb`, `Gemfile` | Ruby |
+| `.java`, `pom.xml` | Java |
+| `.php` | PHP |
+| `.c`, `.cpp` | C/C++ |
+| `.rs`, `Cargo.toml` | Rust |
+| `Dockerfile` | Docker |
+| `.tf` | Terraform |
+| k8s manifests | Kubernetes |
+
+---
+
+## Step 2: Select Scan Mode and Rulesets
+
+> **Entry:** Step 1 complete — languages detected, Pro status known.
+> **Exit:** Scan mode selected; structured rulesets JSON compiled for all detected languages.
+
+**First, select scan mode** using `AskUserQuestion`:
+
+```
+header: "Scan Mode"
+question: "Which scan mode should be used?"
+multiSelect: false
+options:
+  - label: "Run all (Recommended)"
+    description: "Full coverage — all rulesets, all severity levels"
+  - label: "Important only"
+    description: "Security vulnerabilities only — medium-high confidence and impact, no code quality"
+```
+
+Record the selected mode. It affects Steps 4 and 5.
+
+**Then, select rulesets.** Using the detected languages and frameworks from Step 1, follow the **Ruleset Selection Algorithm** in [rulesets.md](../references/rulesets.md).
+
+The algorithm covers:
+1. Security baseline (always included)
+2. Language-specific rulesets
+3. Framework rulesets (if detected)
+4. Infrastructure rulesets
+5. **Required** third-party rulesets (Trail of Bits, 0xdea, Decurity — NOT optional)
+6. Registry verification
+
+**Output:** Structured JSON passed to Step 3 for user review:
+
+```json
+{
+  "baseline": ["p/security-audit", "p/secrets"],
+  "python": ["p/python", "p/django"],
+  "javascript": ["p/javascript", "p/react", "p/nodejs"],
+  "docker": ["p/dockerfile"],
+  "third_party": ["https://github.com/trailofbits/semgrep-rules"]
+}
+```
+
+---
+
+## Step 3: CRITICAL GATE — Present Plan and Get Approval
+
+> **Entry:** Step 2 complete — scan mode and rulesets selected.
+> **Exit:** User has explicitly approved the plan (quoted confirmation).
+
+> **⛔ MANDATORY CHECKPOINT — DO NOT SKIP**
+>
+> This step requires explicit user approval before proceeding.
+> User may modify rulesets before approving.
+
+Present plan to user with **explicit ruleset listing**:
+
+```
+## Semgrep Scan Plan
+
+**Target:** /path/to/codebase
+**Output directory:** $OUTPUT_DIR
+**Engine:** Semgrep Pro (cross-file analysis) | Semgrep OSS (single-file)
+**Scan mode:** Run all | Important only (security vulns, medium-high confidence/impact)
+
+### Detected Languages/Technologies:
+- Python (1,234 files) - Django framework detected
+- JavaScript (567 files) - React detected
+- Dockerfile (3 files)
+
+### Rulesets to Run:
+
+**Security Baseline (always included):**
+- [x] `p/security-audit` - Comprehensive security rules
+- [x] `p/secrets` - Hardcoded credentials, API keys
+
+**Python (1,234 files):**
+- [x] `p/python` - Python security patterns
+- [x] `p/django` - Django-specific vulnerabilities
+
+**JavaScript (567 files):**
+- [x] `p/javascript` - JavaScript security patterns
+- [x] `p/react` - React-specific issues
+- [x] `p/nodejs` - Node.js server-side patterns
+
+**Docker (3 files):**
+- [x] `p/dockerfile` - Dockerfile best practices
+
+**Third-party (auto-included for detected languages):**
+- [x] Trail of Bits rules - https://github.com/trailofbits/semgrep-rules
+
+**Want to modify rulesets?** Tell me which to add or remove.
+**Ready to scan?** Say "proceed" or "yes".
+```
+
+**⛔ STOP: Await explicit user approval.**
+
+1. **If user wants to modify rulesets:** Add/remove as requested, re-present the updated plan, return to waiting.
+2. **Use AskUserQuestion** if user hasn't responded:
+   ```
+   "I've prepared the scan plan with N rulesets (including Trail of Bits). Proceed with scanning?"
+   Options: ["Yes, run scan", "Modify rulesets first"]
+   ```
+3. **Valid approval:** "yes", "proceed", "approved", "go ahead", "looks good", "run it"
+4. **NOT approval:** User's original request ("scan this codebase"), silence, questions about the plan
+
+### Pre-Scan Checklist
+
+Before marking Step 3 complete:
+- [ ] Target directory shown to user
+- [ ] Engine type (Pro/OSS) displayed
+- [ ] Languages detected and listed
+- [ ] **All rulesets explicitly listed with checkboxes**
+- [ ] User given opportunity to modify rulesets
+- [ ] User explicitly approved (quote their confirmation)
+- [ ] **Final ruleset list captured for Step 4**
+- [ ] Agent type listed: `static-analysis:semgrep-scanner`
+
+### Log Approved Rulesets
+
+After approval, write the approved rulesets to `$OUTPUT_DIR/rulesets.txt`:
+
+```bash
+cat > "$OUTPUT_DIR/rulesets.txt" << RULESETS
+# Semgrep Scan — Approved Rulesets
+# Generated: $(date -Iseconds)
+# Scan mode: <run-all|important-only>
+
+## Rulesets:
+<one ruleset per line, e.g.:>
+p/security-audit
+p/secrets
+p/python
+p/django
+https://github.com/trailofbits/semgrep-rules
+RULESETS
+```
+
+---
+
+## Step 4: Spawn Parallel Scan Tasks
+
+> **Entry:** Step 3 approved — user explicitly confirmed the plan.
+> **Exit:** All scan Tasks completed; result files exist in `$OUTPUT_DIR/raw/`.
+
+**Use `$OUTPUT_DIR` resolved in Step 1.** It already exists; no need to create it again. Scanners write all output to `$OUTPUT_DIR/raw/`.
+
+**Spawn N Tasks in a SINGLE message** (one per language category) using `subagent_type: static-analysis:semgrep-scanner`.
+
+Use the scanner task prompt template from [scanner-task-prompt.md](../references/scanner-task-prompt.md).
+
+**Mode-dependent scanner flags:**
+- **Run all**: No additional flags
+- **Important only**: Add `--severity MEDIUM --severity HIGH --severity CRITICAL` to every `semgrep` command
+
+**Example — 3 Language Scan (with approved rulesets):**
+
+Spawn these 3 Tasks in a SINGLE message:
+
+1. **Task: Python Scanner** — Rulesets: p/python, p/django, p/security-audit, p/secrets, trailofbits → `$OUTPUT_DIR/raw/python-*.json`
+2. **Task: JavaScript Scanner** — Rulesets: p/javascript, p/react, p/nodejs, p/security-audit, p/secrets, trailofbits → `$OUTPUT_DIR/raw/js-*.json`
+3. **Task: Docker Scanner** — Rulesets: p/dockerfile → `$OUTPUT_DIR/raw/docker-*.json`
+
+### Operational Notes
+
+- Always use **absolute paths** for `[TARGET]` — subagents can't resolve relative paths
+- Clone GitHub URL rulesets into `$OUTPUT_DIR/repos/` — never pass URLs directly to `--config` (semgrep's URL handling fails on repos with non-standard YAML)
+- Delete `$OUTPUT_DIR/repos/` after all scans complete
+- Run rulesets in parallel with `&` and `wait`, not sequentially
+- Use `--include="*.py"` for language-specific rulesets, but NOT for cross-language rulesets (p/security-audit, p/secrets, third-party repos)
+
+---
+
+## Step 5: Merge Results and Report
+
+> **Entry:** Step 4 complete — all scan Tasks finished.
+> **Exit:** `results.sarif` exists in `$OUTPUT_DIR/results/` and is valid JSON.
+
+**Important-only mode: Post-filter before merge.** Apply the filter from [scan-modes.md](../references/scan-modes.md) ("Filter All Result Files in a Directory" section) to each result JSON in `$OUTPUT_DIR/raw/`. The filter creates `*-important.json` files alongside the originals — the originals are preserved unmodified.
+
+**Generate merged SARIF** using the merge script. The resolved path is in SKILL.md's "Merge command" section — use that exact path:
+
+```bash
+uv run {baseDir}/scripts/merge_sarif.py $OUTPUT_DIR/raw $OUTPUT_DIR/results/results.sarif
+```
+
+- **Run-all mode:** The script merges all `*.sarif` files from `$OUTPUT_DIR/raw/`.
+- **Important-only mode:** Run the post-filter first (creates `*-important.json` in `raw/`), then run the merge script. Raw SARIF files are unaffected by the JSON post-filter, so the merge operates on the unfiltered SARIF. For SARIF-level filtering, apply the jq post-filter from scan-modes.md to `$OUTPUT_DIR/results/results.sarif` after merge.
+
+**Verify merged SARIF is valid:**
+
+```bash
+python -c "import json; d=json.load(open('$OUTPUT_DIR/results/results.sarif')); print(f'{sum(len(r.get(\"results\",[]))for r in d.get(\"runs\",[]))} findings in merged SARIF')"
+```
+
+If verification fails, the merge script produced invalid output — investigate before reporting.
+
+**Report to user:**
+
+```
+## Semgrep Scan Complete
+
+**Scanned:** 1,804 files
+**Rulesets used:** 9 (including Trail of Bits)
+**Total findings:** 156
+
+### By Severity:
+- ERROR: 5
+- WARNING: 18
+- INFO: 9
+
+### By Category:
+- SQL Injection: 3
+- XSS: 7
+- Hardcoded secrets: 2
+- Insecure configuration: 12
+- Code quality: 8
+
+Results written to:
+- $OUTPUT_DIR/results/results.sarif (merged SARIF)
+- $OUTPUT_DIR/raw/ (per-scan raw results, unfiltered)
+- $OUTPUT_DIR/rulesets.txt (approved rulesets)
+```
+
+**Verify** before reporting: confirm `results.sarif` exists and is valid JSON.

package/skills/semgrep-rule-creator/SKILL.md

@@ -0,0 +1,168 @@
+---
+name: semgrep-rule-creator
+description: Creates custom Semgrep rules for detecting security vulnerabilities, bug patterns, and code patterns. Use when writing Semgrep rules or building custom static analysis detections.
+allowed-tools:
+  - Bash
+  - Read
+  - Write
+  - Edit
+  - Glob
+  - Grep
+  - WebFetch
+---
+
+# Semgrep Rule Creator
+
+Create production-quality Semgrep rules with proper testing and validation.
+
+## When to Use
+
+**Ideal scenarios:**
+- Writing Semgrep rules for specific bug patterns
+- Writing rules to detect security vulnerabilities in your codebase
+- Writing taint mode rules for data flow vulnerabilities
+- Writing rules to enforce coding standards
+
+## When NOT to Use
+
+Do NOT use this skill for:
+- Running existing Semgrep rulesets
+- General static analysis without custom rules (use `static-analysis` skill)
+
+## Rationalizations to Reject
+
+When writing Semgrep rules, reject these common shortcuts:
+
+- **"The pattern looks complete"** → Still run `semgrep --test --config <rule-id>.yaml <rule-id>.<ext>` to verify. Untested rules have hidden false positives/negatives.
+- **"It matches the vulnerable case"** → Matching vulnerabilities is half the job. Verify safe cases don't match (false positives break trust).
+- **"Taint mode is overkill for this"** → If data flows from user input to a dangerous sink, taint mode gives better precision than pattern matching.
+- **"One test is enough"** → Include edge cases: different coding styles, sanitized inputs, safe alternatives, and boundary conditions.
+- **"I'll optimize the patterns first"** → Write correct patterns first, optimize after all tests pass. Premature optimization causes regressions.
+- **"The AST dump is too complex"** → The AST reveals exactly how Semgrep sees code. Skipping it leads to patterns that miss syntactic variations.
+
+## Anti-Patterns
+
+**Too broad** - matches everything, useless for detection:
+```yaml
+# BAD: Matches any function call
+pattern: $FUNC(...)
+
+# GOOD: Specific dangerous function
+pattern: eval(...)
+```
+
+**Missing safe cases in tests** - leads to undetected false positives:
+```python
+# BAD: Only tests vulnerable case
+# ruleid: my-rule
+dangerous(user_input)
+
+# GOOD: Include safe cases to verify no false positives
+# ruleid: my-rule
+dangerous(user_input)
+
+# ok: my-rule
+dangerous(sanitize(user_input))
+
+# ok: my-rule
+dangerous("hardcoded_safe_value")
+```
+
+**Overly specific patterns** - misses variations:
+```yaml
+# BAD: Only matches exact format
+pattern: os.system("rm " + $VAR)
+
+# GOOD: Matches all os.system calls with taint tracking
+mode: taint
+pattern-sinks:
+  - pattern: os.system(...)
+```
+
+## Strictness Level
+
+This workflow is **strict** - do not skip steps:
+- **Read documentation first**: See [Documentation](#documentation) before writing Semgrep rules
+- **Test-first is mandatory**: Never write a rule without tests
+- **100% test pass is required**: "Most tests pass" is not acceptable
+- **Optimization comes last**: Only simplify patterns after all tests pass
+- **Avoid generic patterns**: Rules must be specific, not match broad patterns
+- **Prioritize taint mode**: For data flow vulnerabilities
+- **One YAML file - one Semgrep rule**: Each YAML file must contain only one Semgrep rule; don't combine multiple rules in a single file
+- **No generic rules**: When targeting a specific language for Semgrep rules - avoid generic pattern matching (`languages: generic`)
+- **Forbidden `todook` and `todoruleid` test annotations**: `todoruleid: <rule-id>` and `todook: <rule-id>` annotations in tests files for future rule improvements are forbidden
+
+## Overview
+
+This skill guides creation of Semgrep rules that detect security vulnerabilities and code patterns. Rules are created iteratively: analyze the problem, write tests first, analyze AST structure, write the rule, iterate until all tests pass, optimize the rule.
+
+**Approach selection:**
+- **Taint mode** (prioritize): Data flow issues where untrusted input reaches dangerous sinks
+- **Pattern matching**: Simple syntactic patterns without data flow requirements
+
+**Why prioritize taint mode?** Pattern matching finds syntax but misses context. A pattern `eval($X)` matches both `eval(user_input)` (vulnerable) and `eval("safe_literal")` (safe). Taint mode tracks data flow, so it only alerts when untrusted data actually reaches the sink—dramatically reducing false positives for injection vulnerabilities.
+
+**Iterating between approaches:** It's okay to experiment. If you start with taint mode and it's not working well (e.g., taint doesn't propagate as expected, too many false positives/negatives), switch to pattern matching. Conversely, if pattern matching produces too many false positives on safe cases, try taint mode instead. The goal is a working rule—not rigid adherence to one approach.
+
+**Output structure** - exactly 2 files in a directory named after the rule-id:
+```
+<rule-id>/
+├── <rule-id>.yaml     # Semgrep rule
+└── <rule-id>.<ext>    # Test file with ruleid/ok annotations
+```
+
+## Quick Start
+
+```yaml
+rules:
+  - id: insecure-eval
+    languages: [python]
+    severity: HIGH
+    message: User input passed to eval() allows code execution
+    mode: taint
+    pattern-sources:
+      - pattern: request.args.get(...)
+    pattern-sinks:
+      - pattern: eval(...)
+```
+
+Test file (`insecure-eval.py`):
+```python
+# ruleid: insecure-eval
+eval(request.args.get('code'))
+
+# ok: insecure-eval
+eval("print('safe')")
+```
+
+Run tests (from rule directory): `semgrep --test --config <rule-id>.yaml <rule-id>.<ext>`
+
+## Quick Reference
+
+- For commands, pattern operators, and taint mode syntax, see [quick-reference.md]({baseDir}/references/quick-reference.md).
+- For detailed workflow and examples, you MUST see [workflow.md]({baseDir}/references/workflow.md)
+
+## Workflow
+
+Copy this checklist and track progress:
+
+```
+Semgrep Rule Progress:
+- [ ] Step 1: Analyze the Problem
+- [ ] Step 2: Write Tests First
+- [ ] Step 3: Analyze AST structure
+- [ ] Step 4: Write the rule
+- [ ] Step 5: Iterate until all tests pass (semgrep --test)
+- [ ] Step 6: Optimize the rule (remove redundancies, re-test)
+- [ ] Step 7: Final Run
+```
+
+## Documentation
+
+**REQUIRED**: Before writing any rule, use WebFetch to read **all** of these 4 links with Semgrep documentation:
+
+1. [Rule Syntax](https://semgrep.dev/docs/writing-rules/rule-syntax)
+2. [Pattern Syntax](https://semgrep.dev/docs/writing-rules/pattern-syntax)
+3. [ToB Testing Handbook - Semgrep](https://appsec.guide/docs/static-analysis/semgrep/advanced/)
+4. [Constant propagation](https://semgrep.dev/docs/writing-rules/data-flow/constant-propagation)
+5. [Writing Rules Index](https://github.com/semgrep/semgrep-docs/tree/main/docs/writing-rules/)

package/skills/semgrep-rule-creator/references/quick-reference.md

@@ -0,0 +1,202 @@
+# Semgrep Rule Quick Reference
+
+## Required Rule Fields
+
+```yaml
+rules:
+  - id: rule-id          # Unique identifier (lowercase, hyphens)
+    languages:                 # Target language(s)
+      - python
+    severity: HIGH            # LOW, MEDIUM, HIGH, CRITICAL (ERROR/WARNING/INFO are legacy)
+    message: Description      # Shown when rule matches
+    pattern: code(...)        # OR use patterns/pattern-either/mode:taint
+```
+
+## Pattern Operators
+
+### Basic Matching
+```yaml
+pattern: foo(...)              # Match function call
+patterns:                      # AND - all must match
+  - pattern: $X
+  - pattern-not: safe($X)
+pattern-either:                # OR - any can match
+  - pattern: foo(...)
+  - pattern: bar(...)
+pattern-regex: ^foo.*bar$      # PCRE2 regex matching (multiline mode)
+```
+
+### Metavariables
+- `$VAR` - Match any single expression
+  - **Must be uppercase**: `$X`, `$FUNC`, `$VAR_1` (NOT `$x`, `$var`)
+- `$_` - Anonymous metavariable (matches but doesn't bind)
+- `$...VAR` - Match zero or more arguments (ellipsis metavariable)
+- `...` - Ellipsis, match anything in between
+
+### Typed Metavariables
+
+Constrain metavariables to specific types (reduces false positives):
+
+```yaml
+# C/C++ - match only int16_t parameters
+pattern: (int16_t $X)
+
+# C/C++ - match function with typed parameter
+pattern: some_func((int $ARG))
+
+# Java - match Logger type
+pattern: (java.util.logging.Logger $LOGGER).log(...)
+
+# Go - match pointer type (uses colon syntax)
+pattern: ($READER : *zip.Reader).Open($INPUT)
+
+# TypeScript - match specific type
+pattern: ($X: DomSanitizer).sanitize(...)
+
+Use in taint mode to track only specific types as sources:
+pattern-sources:
+  - pattern: (int $X)        # Only int parameters are taint sources
+  - pattern: (int16_t $X)    # Only int16_t parameters
+  - pattern: int $X = $INIT; # Local variable declarations
+
+
+### Deep Expression Matching
+```yaml
+<... $EXPR ...>               # Recursively match pattern in nested expressions
+```
+
+### Scope Operators
+```yaml
+pattern-inside: |              # Must be inside this pattern
+  def $FUNC(...):
+    ...
+pattern-not-inside: |          # Must NOT be inside this pattern
+  with $CTX:
+    ...
+```
+
+### Negation
+```yaml
+pattern-not: safe(...)         # Exclude this pattern
+pattern-not-regex: ^test_      # Exclude by regex
+```
+
+### Metavariable Filters
+```yaml
+metavariable-regex:
+  metavariable: $FUNC
+  regex: (unsafe|dangerous).*
+
+metavariable-pattern:
+  metavariable: $ARG
+  pattern: request.$X
+
+metavariable-comparison:
+  metavariable: $NUM
+  comparison: $NUM > 1024
+```
+
+### Focus
+```yaml
+focus-metavariable: $TARGET    # Report finding on this metavariable only
+```
+
+## Taint Mode
+
+```yaml
+rules:
+  - id: taint-rule
+    mode: taint
+    languages: [python]
+    severity: HIGH
+    message: Tainted data reaches sink
+    pattern-sources:
+      - pattern: user_input()
+      - pattern: request.args.get(...)
+    pattern-sinks:
+      - pattern: eval(...)
+      - pattern: os.system(...)
+    pattern-sanitizers:           # Optional
+      - pattern: sanitize(...)
+      - pattern: escape(...)
+```
+
+### Taint Options
+```yaml
+pattern-sources:
+  - pattern: source(...)
+    exact: true                   # Only exact match is source (default: false)
+    by-side-effect: true          # Taints variable by side effect
+
+pattern-sanitizers:
+  - pattern: sanitize($X)
+    exact: true                   # Only exact match (default: false)
+    by-side-effect: true          # Sanitizes by side effect
+
+pattern-sinks:
+  - pattern: sink(...)
+    exact: false                  # Subexpressions also sinks (default: true)
+```
+
+## Test File Annotations
+
+Only allowed annotations are `ok: rule-id` and `ok: rule-id`.
+
+```python
+# ruleid: rule-id
+vulnerable_code()              # This line MUST match
+
+# ok: rule-id
+safe_code()                    # This line MUST NOT match
+```
+
+DO NOT use multi-line comments for test annotations, for example:
+/* ruleid: ... */
+
+## Debugging Commands
+
+```bash
+# Test rules
+semgrep --test --config <rule-id>.yaml <rule-id>.<ext>
+
+# Validate YAML syntax
+semgrep --validate --config <rule-id>.yaml
+
+# Run with dataflow traces (for taint mode rules)
+semgrep --dataflow-traces -f <rule-id>.yaml <rule-id>.<ext>
+
+# Dump AST to understand code structure
+semgrep --dump-ast -l <language> <rule-id>.<ext>
+
+# Run single rule
+semgrep -f <rule-id>.yaml <rule-id>.<ext>
+```
+
+## Troubleshooting
+
+### Common Pitfalls
+
+1. **Wrong annotation line**: `ruleid:` must be on the line IMMEDIATELY BEFORE the finding. No other text or code
+2. **Too generic patterns**: Avoid `pattern: $X` without constraints
+3. **YAML syntax errors**: Validate with `semgrep --validate`
+
+### Pattern Not Matching
+
+1. Check AST structure: `semgrep --dump-ast -l <language> <rule-id>.<ext>`
+2. Verify metavariable binding
+3. Check for whitespace/formatting differences
+4. Try more general pattern first, then narrow down
+
+### Taint Not Propagating
+
+1. Use `--dataflow-traces` to see flow
+2. Check if sanitizer is too broad
+3. Verify source pattern matches
+4. Check sink focus-metavariable
+
+### Too Many False Positives
+
+1. Add `pattern-not` for safe cases
+2. Add sanitizers for validation functions
+3. Use `pattern-inside` to limit scope
+4. Use `metavariable-regex` to filter