Mantis ArchitectureSAFE

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-architecture
description: >-
  Synthesizes raw learnings and codebase analysis into an interlinked Markdown Knowledge Base (KB).
  Use at the beginning of a loop to build or update architecture.md, entities, and vulnerabilities.
  Don't use for generating threat models or formulating execution plans.
---

# Architect (/mantis-architecture)

## System Goal

Knowledge Base Synthesizer. Translates ephemeral insights from the learnings
queue (`workspace/learnings.jsonl`) and structural analysis of the codebase into
a canonical, interlinked Markdown Knowledge Base (`workspace/kb/`).

## Command Definition

- **Command:** `/mantis-architecture`
- **Description:** Builds the foundation of the KB by defining system
  architecture, mapping specific entities (components), and categorizing
  historical vulnerability patterns.
- **Arguments (all optional; resolved by LOCATOR RESOLUTION / Block A):**
  `--snapshot_root=<dir>` (or the `SNAPSHOT_ROOT` env var) — the pinned code
  snapshot to read target source from; `--snapshot_id=<id>` — the `SNAPSHOT_ID`
  of that snapshot; `--state_root=<dir>` — the parent of `workspace/` for all
  state and KB paths; `--target_root=<dir>` — an already-prepared tree that
  OVERRIDES the snapshot (rarely passed to this stage). When none are passed,
  behavior is byte-for-byte today's (degraded/unpinned): read source from the
  current directory and treat `snapshot_pinned` as false.

## Input/Output Contract

- **Reads**:
  - `workspace/learnings.jsonl` (raw insights from the current round).
  - `workspace/historical_learnings.jsonl` (optional, past vulnerability
    metadata).
  - Codebase directory structure and key source files.
  - Existing Markdown files in `workspace/kb/` (to validate/decay check).
  - `workspace/.mantis_state.json` (to retrieve pass count).
  - `workspace/.mantis_state.json` → `active_snapshot` (`root`, `snapshot_id`,
    `snapshot_pinned`) and `snapshot_history` — provenance for the KB freshness
    gate (step 0b). Read the snapshot from STATE ONLY; NEVER run a live VCS
    command (`git`/`hg`/`repo`) to decide KB currency.
  - `workspace/.mantis_state.json` → `kb_snapshot_id` (the `SNAPSHOT_ID` the
    current KB was last built against; absent on a first/legacy KB).
  - `workspace/.mantis_state.json` → `changed_files` and `changed_files_status`
    (written by mantis-plan's Block E; consumed by the scoped KB invalidation in
    step 0b outcome 3. Present from pass 2 on, but may be stale (written in a
    prior pass) — the scoped path checks `changed_files_pass` against
    `state.pass_number` and falls back to full rebuild if they differ.)
- **Writes**:
  - Markdown files under `workspace/kb/` (`architecture.md`,
    `entities/[component_name].md`, `vulnerabilities/[CWE-ID].md`, `index.md`).
  - `workspace/kb/dependencies.json` — a JSON map of import/dependency edges
    extracted during architectural analysis (keys = source file paths relative
    to CODE_ROOT; values = arrays of files that import/depend on the key file).
    This is consumed by `mantis-plan`'s dependency-aware fan-out (Phase 2). If
    the codebase has no parseable import structure, write `{}`. Re-derive only
    changed entries during scoped invalidation (see outcome 3 below).
  - Archives `workspace/learnings.jsonl` to
    `workspace/archive/learnings/learnings_pass_${N}_${X}.jsonl`.
  - A `<!-- KB_SNAPSHOT: <SNAPSHOT_ID> -->` marker as the FIRST line of every
    (re)written KB file (`index.md`, each `entities/*.md`, each
    `vulnerabilities/*.md`), plus `kb_snapshot_id` = `SNAPSHOT_ID` in
    `workspace/.mantis_state.json`.
  - An immutable per-pass copy of the whole KB tree to
    `workspace/archive/kb/kb_pass_${N}_${X}/` (so a later reverted fix cannot
    silently erase the record of what the KB claimed at pass N).
- **Preconditions**:
  - `workspace/learnings.jsonl` must exist.
- **Idempotency Guarantee**:
  - Transactional: moves `workspace/learnings.jsonl` to archive only after
    programmatically verifying all KB Markdown updates were written
    successfully. KB files are overwritten in-place.
  - Snapshot stamping is part of the same transaction: the `KB_SNAPSHOT`
    markers, the per-pass `workspace/archive/kb/kb_pass_${N}_${X_kb}/` copy, and
    the `kb_snapshot_id` state write complete before (or together with) the
    learnings move. On any failure, leave `workspace/learnings.jsonl` intact.

## Instructions

Analyze the codebase and pending learnings to construct a permanent,
Markdown-based memory for future agents.

Execute the architecture stage as follows:

0. **LOCATOR RESOLUTION (Block A, inlined below):**

```
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:
   - SNAPSHO

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 Architecture](https://modelsatlas.com/skills/google/mantis-architecture/badge.svg)](https://modelsatlas.com/skills/google/mantis-architecture/)

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