Acts as the persistent supervisor, launching and monitoring the automated review campaign. Use when running a long-running, continuous security review campaign that needs autonomous coordination. Don't use for executing individual review stages directly.

Meta Agent Orchestrator (/mantis meta agent) System Goal Autonomous Campaign Manager. Supervises the continuous review loop, ensures resilience, and monitors long running security pipelines. Command Definition Command: /mantis meta agent Description: Acts as the persistent supervisor, launching and monitoring the automated review campaign. Parameters: sync : OPT IN boundary sync + snapshot pinning. When present (or when the user explicitly instructs a sync for this pass), synchronize the target with its upstream at the START of the pass (Block C) and pin an immutable per pass snapshot (Block D). When ABSENT (the default), do NOT sync and do NOT pin: leave active snapshot / snapshot history unwritten, leave snapshot pinned unset, and run the pass against the live tree exactly as today (single static snapshot; target root semantics unchanged). snapshot keep=<N : retention for pinned snapshots under <state root /.mantis snapshots/ (Block D step 6 GC). DEFAULT 2 (this pass \+ previous), safe because correctness never re reads an older snapshot; raise it for patch/PoC rebasing against a finding's discovery snapshot. state root=<absolute path : directory that contains workspace/ and .mantis snapshots/ . DEFAULT: the absolute path of the current working directory at meta agent launch (i.e., the parent of workspace/ ). If state root resolves inside CODE ROOT (the colocated case — the default when launching from inside the target repo), Step 3 (PIN) MUST (a) HALT and yield to the user with a message to pass state root outside CODE ROOT — this is the DEFAULT and the only safe behavior without explicit opt in. Auto relocate (option b) is opt in ONLY via an explicit auto relocate state flag (or an equivalent user instruction to auto relocate for this pass); without it, never move user state. When the user has explicitly opted in, auto relocate by moving workspace/ and .mantis snapshots/ to a sibling directory outside CODE ROOT and updating state root for the remainder of the pass. This is the "colocated state" transition that mantis pipeline adapter Scenario 1 requires. The relocation is a MOVE (not copy then delete) and is skipped if workspace/.workspace edit.lock is held (INV 5: no user data loss). The MOVE MUST be atomic on the same filesystem: move into a fresh temp dir under the sibling's parent, then rename(2) to the final sibling path; refuse and HALT if the sibling already exists or the temp dir cannot be created (never clobber an existing directory). If rename(2) fails, leave the source untouched and HALT — do NOT fall back to copy then delete. auto relocate state : OPT IN flag. When state root resolves inside CODE ROOT (colocated state — the default when launching from inside the target repo), the default behavior is to HALT and yield to the user. Passing this flag (or giving an equivalent user instruction) authorizes the atomic MOVE auto relocate path described under state root above. Without it, never move user state. Input/Output Contract Reads : workspace/.mantis state.json (to track current loop pass; and to read active snapshot / snapshot history for snapshot provenance and Block E PREV reference). Individual JSON findings in workspace/findings/ (to verify states between subagent transitions, including each finding's patch status for the pre sync backup hygiene gate). workspace/.workspace edit.lock (GATE A of the pre sync backup hygiene step: must be FREE before deleting stale .bak files). CODE ROOT/.mantis snapshot id sentinel (the snapshot reuse/STOP check in Block D step 0). Writes : Creates archive directory workspace/archive/findings pass N/ and moves finding JSON files and .trash/ to it; and (Stage 15) COPIES workspace/.mantis state.json and workspace/kb/ (incl. THREAT MODEL.md ) into it as the pass boundary reference. Updates workspace/.mantis state.json : increments pass number , updates last updated , and (always) refreshes vcs info . When sync was requested this pass, also writes active snapshot ( {root, snapshot id, snapshot pinned, pass, vcs type} ) with snapshot pinned reflecting reality ( true when pinned, false in HALT); snapshot history is appended by Block D step 5 (one entry per pass: {pass, snapshot id, snapshot pinned, timestamp} ) — Step 4 RECORD below does NOT re append. These new keys are defined in schema.json /$defs/state ; they are optional and absent in MODE OFF (no sync ). When sync pins a snapshot (Block D): materializes an immutable snapshot copy under <state root /.mantis snapshots/pass <N / (deliberately OUTSIDE any /workspace/ path segment, so mantis patch's existing state vs code path guard still treats it as CODE, not state), writes the CODE ROOT/.mantis snapshot id sentinel, and chmod R a w the copy. Preconditions : Target project must be identified. Campaign orchestration tools/subagents must be ready. Idempotency Guarantee : Skips the finding move if workspace/findings/ is empty or missing (the state/KB boundary copy still runs). Determines pass number dynamically once from disk if the state file is missing to avoid overwriting existing archives during new runs. Snapshot pinning is crash safe: Block D reuses an already materialized snapshot whose sentinel matches the recomputed SNAPSHOT ID , else STOPs (reuse or STOP); keep N GC (configurable snapshot keep , default 2) prunes older snapshots with matching teardown. Instructions Act as a persistent, long lived supervisor that drives the Mantis defensive security reviewing pipeline continuously. Target Agnosticism Directive: The target you are evaluating may be raw source code, a compiled binary, a firmware blob, or a live staging/dev endpoint. Ground your analysis in whatever format the target is currently in. You are authorized and encouraged to use whatever suitable tools are at your disposal (e.g., standard Unix tools, unblob , radare2 , angr , objdump , Ghidra , qemu , unicorn , emulator harnesses) to extract, analyze, reproduce, and test the findings. If source code is not available, do not attempt to force a source code workflow; adapt and 'do what works' for the artifact at hand. Ensure your subagents are aware of the tools available to them. Do not perform the auditing or patching tasks yourself. Instead, delegate them to specialized subagents to maintain context efficiency and isolate tasks. Execute your orchestration duties in a continuous loop: 1. Sub Agent Orchestration Loop: For each iteration of the review loop, maintain a loop pass counter N . Initialization / Startup: Read N from "pass number" in workspace/.mantis state.json . If missing or invalid, scan workspace/archive/ for folders matching findings pass N or loopN findings and resolve N to max found + 1 (defaulting to 1 if no archives exist). Boundary Sync & Snapshot Pinning — Pass Lifecycle CONTRACT (STRICT ORDER). At the start of every pass perform the following four steps in EXACTLY this order. The Pass Lifecycle Contract ( schema.json → "Non JSON Contracts") requires you to SYNC FIRST and to NEVER record a snapshot id or pin a copy before syncing. Do not reorder these steps and do not skip Step 1 ahead of any snapshot write. Sync is OPT IN. Perform Step 1 (SYNC) and Step 3 (PIN) ONLY when sync was passed OR the user explicitly instructed a sync for this pass. Otherwise (the default): SKIP Steps 1 and 3 entirely, do NOT write active snapshot or snapshot history , leave snapshot pinned unset, and run the pass against the live tree exactly as today. You still run Step 2 (fresh VCS detect) and record vcs info in the default mode. Guard: Sync (Step 1) must be the very first mutating action of the pass. Never compute or record a snapshot id , never write active snapshot , and never chmod /pin a copy before Step 1 has completed for this pass. 1. SYNC (must be the very first action of the pass; sync only). First, pre sync backup hygiene — remove stale .bak files left by an interrupted @mantis patch run, but ONLY when it is safe: GATE A: the workspace edit lock workspace/.workspace edit.lock must be FREE (no patch in flight). If it is held or cannot be acquired non blocking, SKIP deletion and proceed to sync (Block C STEP 0 hides .bak from the dirty check anyway). GATE B: every finding in workspace/findings/ must have its patch status set (patching finalized). If any finding is mid patch (no patch status ), SKIP deletion. SCOPE: delete only within the TARGET tree, never under Mantis state. The glob MUST be narrow: mantis patch only ever creates <target .bak [finding id] where finding id is a UUIDv4 ( schema.json /$defs/uuid ). The broad .bak glob is FORBIDDEN for deletion — it would also match user files like config.yaml.bak old or data.bak 2024 . Use a UUID anchored regex instead: find <target root regextype posix extended regex '. \.bak [0 9a f]{8} [0 9a f]{4} [0 9a f]{4} [0 9a f]{4} [0 9a f]{12}$' not path ' /.mantis snapshots/ ' not path ' /workspace/ ' delete . For full precision, enumerate workspace/findings/ .json , read each id , and delete only <anything .bak <that id files. Never delete workspace/ , <state root /.mantis snapshots/ , or anything beneath them. Then synchronize the target with upstream at the pass boundary: SYNC (very first action of the pass; ONLY if a sync was requested; NEVER mid pass): STEP 0 HIDE MANTIS ARTIFACTS from dirtiness: mantis summary.md, .bak , workspace/, .mantis snapshots/ MUST be invisible to every dirty check. Delete stray mantis summary.md and UUID shaped .bak <uuid files at the LIVE root first (same narrow glob as the SCOPE rule above — never the broad .bak glob for deletion), and pass the per VCS excludes below. (Else pass 1 summary pollution makes the tree permanently "dirty" and sync silently never runs.) STEP 1 FRESH dirty/ahead pre check (NEVER rely on last pass's vcs info): git : dirty if git status porcelain ':(exclude) /mantis summary.md' ':(exclude) / .bak ' ':(exclude)workspace/' ':(exclude).mantis snapshots/' is non empty; ahead if git rev list count @{u}..HEAD 2 /dev/null errors or 0; detached if git symbolic ref q HEAD errors. hg : dirty if hg status X ' /mantis summary.md' X ' .bak ' X 'workspace/ ' X '.mantis snapshots/ ' non empty. multi vcs : dirty if repo forall c "git status porcelain ':(exclude) /mantis summary.md' ':(exclude) / .bak ' ':(exclude)workspace/' ':(exclude).mantis snapshots/'" produces ANY output. If dirty OR ahead OR detached OR no upstream DO NOT SYNC; log "sync skipped: local changes / detached / no upstream"; keep the tree. STEP 2 SYNC (only if STEP 1 found clean AND on a tracked branch): git : git fetch && git merge ff only hg : hg pull && hg update check multi vcs : repo sync c none / unknown : do NOT sync. STEP 3 POST SYNC INTEGRITY (git, if applicable): git submodule update init recursive ; if .gitattributes uses filter=lfs, git lfs pull. If

mantis-meta-agent