Parsentry

Parsentry Scan Orchestrator

Run parsentry model → agent writes model.json → parsentry scan → parallel agents write SARIF → parsentry generate (merges SARIF + renders PDF).

Phase 1: Threat Model

MODEL_PROMPT=$(parsentry model <TARGET> 2>/dev/null)

Dispatch one Agent with $MODEL_PROMPT as the prompt verbatim. The prompt already instructs the agent to write model.json to the correct cache path — no additional wrapping needed.

Validate before proceeding:

parsentry scan <TARGET> 2>&1 | head -1
# Must NOT say "model.json not found"

Phase 2: Per-Surface Analysis

SCAN_OUTPUT=$(parsentry scan <TARGET> 2>&1)

• If output says "all N surfaces cached, no analysis needed" → skip to Phase 3.
• Otherwise, list all prompt.md files that have no sibling result.sarif.json:

# Parse report paths from parsentry scan output (platform-independent)
parsentry scan <TARGET> 2>&1 | grep '→' | awk '{print $NF}' | while read dir; do
  [ -f "$dir/prompt.md" ] && [ ! -f "$dir/result.sarif.json" ] && echo "$dir"
done

Dispatch all pending surface agents in parallel (single message, multiple Agent tool calls). Pass each prompt.md content verbatim — it already contains surface metadata, source file paths, SARIF schema, and output path.

Validate — re-run parsentry scan <TARGET> and confirm all surfaces are cached.

Phase 3: Report

parsentry generate <TARGET>

generate merges the per-surface SARIF files into merged.sarif.json and renders the PDF in one step. Open the generated PDF path (printed to stdout) and summarize findings to the user.

To file findings as issues instead of (or alongside) a PDF, run parsentry merge <TARGET> --gh-issue <owner/repo> (also supports --jira, --linear, --notion, --min-level, --dry-run).

Phase 4: Triage (on request)

When the user asks to triage, patch, or fix findings, read references/triage.md for the full workflow.

Gotchas

• parsentry model output goes to stdout; progress/logs go to stderr. Always use 2>/dev/null or 2>&1 intentionally.
• The cache directory is platform-dependent (~/Library/Caches/parsentry/ on macOS, ~/.cache/parsentry/ on Linux). Let parsentry scan resolve paths — don't hardcode.
• Agent prompts from parsentry are self-contained. Do not add system prompts or wrap them — pass verbatim.
• parsentry generate merges SARIF internally before rendering — no separate merge step is required for the PDF. The standalone parsentry merge is only for issue-tracker integration (--gh-issue/--jira/--linear/--notion).
• If an agent produces invalid SARIF, the merge step skips that surface and logs a warning. Check generate output for skipped surfaces.

Error Handling

• Agent failure → retry that surface once
• Rate limit (429/529) → wait with exponential backoff, then retry
• Invalid SARIF → log, skip surface, note in final summary