Mantis PlanSAFE

A modular, stack-agnostic toolkit for AI coding agents to autonomously find, reproduce, and patch vulnerabilities.

The instruction file, verbatim from the audited commit — this is the text the model reads, and the surface the audit's instruction layer examines. Quoted here so you can judge it without cloning anything.

---
name: mantis-plan
description: >-
  Formulates a targeted defensive security reviewing plan based on the active threat model and historical learnings.
  Use when starting a security review campaign to map the codebase boundaries and generate a roadmap (workspace/plan.json).
  Don't use for executing code reviews, writing test scripts, or patching code.
---

# Strategist (/mantis-plan)

## System Goal

Security Architect. Analyzes code structure, directory metadata, and historical
records to map the external boundary and formulate an adaptive review roadmap.

## Command Definition

- **Command:** `/mantis-plan`
- **Description:** Formulates a targeted defensive security reviewing plan based
  on the active threat model and historical learnings.
- **Arguments (optional; supplied by the orchestrator, consumed by Block A):**
  - `--snapshot_root` / `SNAPSHOT_ROOT`: absolute path to the pinned read-only
    code snapshot (CODE_ROOT for all snapshot-relative paths).
  - `--snapshot_id` / `SNAPSHOT_ID`: the pass snapshot identifier (sentinel +
    Block B comparisons).
  - `--state_root`: absolute path to the `workspace/` state dir (plan.json,
    .mantis_state.json, findings/, kb/, archive/). STATE-RELATIVE — never
    prefixed with CODE_ROOT.
  - All flags absent -> MODE-OFF/legacy mode (Block A step 1d): behaves exactly
    as today.

## Input/Output Contract

- **Reads**:
  - `workspace/.mantis_state.json` (to track current loop pass).
  - `workspace/kb/THREAT_MODEL.md` (if exists).
  - `workspace/kb/index.md` (checks existence to determine Mode A vs B).
  - Mode A: traverses production directories and source files, reads
    `mantis-summary.md` (if available).
  - Mode B: reads `workspace/kb/index.md`, `workspace/kb/THREAT_MODEL.md`,
    `workspace/archive/.repro_attempts.json` (if exists), VCS diffs or file
    timestamps/hashes.
  - `workspace/kb/structural_index/manifest.json` (to check structural index
    availability/status).
  - `workspace/helpers/query_structural_index.py` (to invoke bounded
    structural-index queries).
  - `workspace/.mantis_state.json` NEW fields:
    `active_snapshot.{snapshot_id, snapshot_pinned, vcs_type}`,
    `snapshot_history` (read, written by the meta-agent). `vcs_type` is read
    because Block E branches on it. Plan runs Block E in the LIVE repo root to
    compute `changed_files` / `changed_files_status` (COMPUTED or UNKNOWN) and
    writes them back to state.
- **Writes**:
  - `workspace/plan.json`.
  - Copies retry-eligible finding JSON files from
    `workspace/archive/findings_pass_K/` or `workspace/archive/loopK_findings/`
    (where K is the pass it was archived in) to `workspace/findings/`
    (preserving their original UUID filenames).
- **Preconditions**:
  - Codebase must be accessible.
- **Idempotency Guarantee**:
  - Overwrites `workspace/plan.json` directly. In Mode B, copies a finding back
    verbatim only when Block B is MATCHED and its file is unchanged and present;
    otherwise it schedules a fresh re-discovery investigation. Consults
    `.repro_attempts.json` under the cache read rule.

## Instructions

### Step 0: Locator Resolution (run before everything else)

```
LOCATOR RESOLUTION (before reading ANY target code or artifact):
0. ROLE: If this skill NEVER reads target source (report, calibrate, reflect),
   you are a FINDINGS-ONLY stage: skip steps 2-6; still read active_snapshot from
   state for provenance/annotation; NEVER stop merely because a code root is unset.
1. Determine CODE_ROOT, in this priority order:
   a. If --target_root is passed on THIS invocation, CODE_ROOT = --target_root.
      It is AUTHORITATIVE and OVERRIDES SNAPSHOT_ROOT and the state fallback
      (used when a caller hands you a prepared tree, e.g. a patched shadow).
   b. Else if --snapshot_root (or SNAPSHOT_ROOT) is passed, use it.
   c. Else read state_root/workspace/.mantis_state.json (state_root from
      --state_root if passed, else ./workspace/... relative to the current dir)
      -> active_snapshot.root / .snapshot_id / .snapshot_pinned.
   d. Else (no arg AND no readable active_snapshot): CODE_ROOT = current directory,
      treat snapshot_pinned = false (MODE-OFF). Do NOT stop.
2. SENTINEL CHECK (only if snapshot_pinned is true AND you did NOT take path 1a):
   verify CODE_ROOT/.mantis_snapshot_id exists and equals SNAPSHOT_ID. If missing
   or different -> STOP "snapshot sentinel mismatch". (A --target_root tree (1a) is
   deliberately mutated and is sentinel-EXEMPT.)
3. PATH FIELDS:
   - SNAPSHOT-RELATIVE (read under CODE_ROOT): code_paths entries; plan target_files
     that are file paths. Strip ONLY a trailing ":<digits>". A code_paths entry
     containing "://" is a URL/endpoint, NOT a file read. A code_paths entry that is
     NOT of the form <existing-path>:<integer> is a non-source LOCATOR
     (symbol/offset/endpoint): only check that the artifact/symbol exists; skip ALL
     line-range and line-existence logic.
   - STATE-RELATIVE (read/write under state_root/workspace, NEVER prefix CODE_ROOT):
     kb_references, repro_file_path, reattack_file_path, helper scripts, report
     files, and all state/findings JSON.
4. Never WRITE under CODE_ROOT when snapshot_pinned is true. Any command that
   compiles, generates, or writes artifacts MUST run in a PRIVATE SHADOW copy
   (mktemp -d from CODE_ROOT), never with cwd=CODE_ROOT. Read-only inspection may
   cd into CODE_ROOT.
5. VCS-METADATA CARVE-OUT: history-log extraction and any VCS diff/blame command
   run in the LIVE repository root (which still has .git/.hg/.repo), NOT CODE_ROOT
   (the snapshot copy strips VCS metadata). Do NOT stop merely because CODE_ROOT
   lacks .git/.hg/.repo.
6. Every shell command uses ABSOLUTE paths and sets its own working directory on
   that call. Do NOT assume the working directory persists between calls.
```

> [!NOTE] **CURRENT-PASS CHECK (defensive; the binding guarantee is on the
> harness per `mantis-pipeline-adapter` Scenario 2):** if `

SAFEgrade B · trust 89/100 Nothing in the source contradicts what it says it does. Grade A is reserved for packages that have also passed the behavioural sandbox.

What the source does

Filesystem

none-observed

Network

none-observed

Shell

none-observed

Dependencies

pinned

Secrets in source

none-found

Findings (0)

No findings outside the package's declared scope.

Gates applied: no_behavioural_pass.

[![ModelsAtlas audit: Mantis Plan](https://modelsatlas.com/skills/google/mantis-plan/badge.svg)](https://modelsatlas.com/skills/google/mantis-plan/)

Not your listing, or something out of date? Claim or update your listing.