Skip to content

mantis-architecture

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.

1,549
installs
0 up / 0 down, score 0.00
votes
2,514
repo stars
Updated
less than a month ago
In the catalog since
1 Oct 2026
From
google/mantis
Documentation & Writing
Get it through your agent npx skills add google/mantis@mantis-architecture

Skill instructions

Rendered from the published SKILL.md, 347 lines.

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:

  1. 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:
   - 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.
Show the whole skill (227 more lines) 

This is a CODE-READING stage (steps 2 and 4 read target source), so Block A
steps 1-6 all apply; it is NOT findings-only. Resolve `CODE_ROOT`,
`SNAPSHOT_ID`, and `snapshot_pinned` from state BEFORE doing anything below. Per
Block A step 3, all `workspace/kb/...` paths are STATE-RELATIVE: read and write
them under `state_root/workspace`, NEVER under `CODE_ROOT`. Read all target
source under `CODE_ROOT`. Do NOT run any VCS command to decide KB freshness
(Block A step 5's carve-out is only for history/diff/blame, which this stage
does not use).

0b. **KB SNAPSHOT FRESHNESS GATE (mechanical; STATE + KB marker only, NO live
VCS):**

  • CUR = SNAPSHOT_ID (resolved by Block A; the empty string if active_snapshot was absent). PINNED = snapshot_pinned (false if absent).

  • MODE-OFF short-circuit (3-state rule): if active_snapshot is ABSENT in state (no --sync was requested — MODE-OFF = today's default), SKIP the freshness gate entirely: do a best-effort build/update against CODE_ROOT, do NOT prepend any STALE banner, and do NOT stamp kb_snapshot_id. This is byte-for-byte today's behavior. (Only HALT and PINNED run the gate below.)

  • KB_ID = the kb_snapshot_id value in .mantis_state.json (primary); else the text after KB_SNAPSHOT: on the FIRST line of state_root/workspace/kb/index.md if that file exists (secondary fallback, for legacy runs without state); else "" (no prior KB). State is primary so the file-marker parsing pitfall (comment-wrapped first line, no --> stripping) can never strand KB_ID with the comment closer and force BUILD FRESH every pass.

  • Choose EXACTLY ONE outcome by string checks, top to bottom, first match wins:

    1. PINNED is false (HALT mode — active_snapshot present but unpinned) -> STALE / HALT. Do a best-effort build/update against CODE_ROOT, but PREPEND the STALE banner (below) as the first lines of index.md. Do NOT claim currency: leave the banner in place. Set kb_snapshot_id = CUR (a live: id).
    2. Else KB_ID == CUR (both non-empty) -> CURRENT. Do the incremental update + decay-check (step 4) as today. Re-stamp KB_SNAPSHOT: CUR on every (re)written file. REMOVE any STALE banner previously prepended to index.md.
    3. Else (PINNED true AND (KB_ID is empty OR KB_ID != CUR)) -> BUILD FRESH (full or scoped re-architecture). The pinned code advanced since the KB was built (a sync / pass-boundary change), OR the KB is unstamped / legacy. Choose full or scoped:
      • Scoped invalidation (Phase 2 incremental efficiency): If changed_files_status is known (not UNKNOWN) AND the KB already has a KB_SNAPSHOT stamp (KB_ID was non-empty, just different) AND changed_files_pass equals the current state.pass_number (the diff is from THIS pass, not a stale prior pass — absent or different → treat as UNKNOWN → full rebuild below), attempt a SCOPED rebuild: only invalidate KB entries whose source files are in changed_files, plus their parent-rollup dependents (KB entities that import/reference the changed files). Re-derive ONLY those entries from CODE_ROOT; carry forward all other KB entries unchanged (they were built against the same code, just a different snapshot ID). Re-stamp KB_SNAPSHOT: CUR on every (re)written file.
        • Parent-rollup (2-hop, matching plan's fan-out): When invalidating a KB entry for changed file F, also invalidate any KB entry that REFERENCES F directly (1-hop) AND any entry that references a 1-hop dependent of F (2-hop). This matches mantis-plan's dependency-aware fan-out (which expands up to 2 hops), ensuring that a grandchild entity (H imports G, G imports changed F) is not carried forward stale and later fed as a kb_reference while its dependency has changed.
        • Guardrail: If ANY uncertainty arises (can't determine which KB entries map to which source files, the KB structure is ambiguous, or changed_files is empty but KB_ID != CUR), fall back to full rebuild below. Never carry forward a stale entry for a changed file.
      • Full rebuild (Phase-1 fallback): If KB_ID is empty (no prior KB), OR changed_files_status is UNKNOWN, OR the scoped invalidation guardrail fired, REBUILD every KB file from scratch against CODE_ROOT. Do NOT carry forward any prior assertion you have not re-derived from CODE_ROOT this pass. Stamp KB_SNAPSHOT: CUR. REMOVE any STALE banner.

  • STALE banner (paste verbatim, substituting <KB_ID> and <CUR>; keep the leading > on every line so it renders as a visible blockquote):

    > **STALE KB WARNING — do not trust without re-verifying.**
> snapshot_pinned=false, or the KB was built against a different snapshot.
> KB_SNAPSHOT=<KB_ID> does not match active_snapshot.snapshot_id=<CUR>.
> Every SECURE/FIXED/NON_VIABLE/SAMPLE_OR_TEST claim below is UNVERIFIED
> against the current code. Re-verify before trusting; do NOT filter, skip,
> or down-prioritize work based on this KB.


1. **Read the Inbox (`workspace/learnings.jsonl` and
   `workspace/historical_learnings.jsonl`):**

   - Parse the contents of `workspace/learnings.jsonl` (and
     `workspace/historical_learnings.jsonl` if it exists). Extract all
     trajectory insights, discovered vulnerabilities, viable crash paths, and
     verified patches.

2. **Analyze Source Code Boundaries:**

   - Examine the directory structure and key source files **under `CODE_ROOT`**
     (the pinned snapshot resolved by Block A; use absolute paths per Block A
     step 6, and do NOT run a VCS command). Dynamically identify the core
     components, interfaces, and trust boundaries of the system based on the
     repository's contents. This applies broadly across domains: whether it is a
     software system (e.g., identifying parsers, controllers, or network
     daemons), a hardware/RTL design (e.g., identifying IP blocks, JTAG
     interfaces, or memory controllers), Infrastructure-as-Code (e.g.,
     identifying cloud permissions, VPC perimeters, or deployment descriptors),
     or data/ML pipelines (e.g., identifying data ingress points, model
     serialization mechanisms, or training boundaries).

3. **Build or Update the Knowledge Base (KB):**

   - Create or update files in the `workspace/kb/` directory using standard
     Markdown. Follow these strict paths:

     - `workspace/kb/architecture.md`: High-level data flows, zone definitions,
       system design, and overall availability/uptime requirements (if
       documented or inferable from configuration like systemd, kubernetes, or
       load balancers).
     - `workspace/kb/entities/[component_name].md`: Specific definitions for
       components (e.g., `auth_module.md`). Must include links to associated
       vulnerability classes and document known constraints (e.g., "This module
       sanitizes input X"). Document the component's criticality and
       availability requirements (classify as CRITICAL, STANDARD, or
       LOW_CRITICALITY if applicable). Incorporate trajectory insights here.
     - `workspace/kb/vulnerabilities/[CWE-ID_or_BugClass].md`: Descriptions of
       bug classes (e.g., `CWE-79.md` or `Memory-Corruption.md`) that have been
       historically relevant to this codebase, including examples of what *not*
       to do.
     - `workspace/kb/index.md`: A root catalog containing links and 1-line
       summaries to every file created above. This is the map the Planner will
       read.

   - **Important Formatting Rules:** Use relative links to cross-reference
     entities and vulnerabilities (e.g.,
     `[Auth Module](entities/auth_module.md)`). Ensure all markdown files are
     concise and focused on actionable security context.

   - **Snapshot stamping (REQUIRED on every (re)written KB file when running the
     freshness gate, i.e. HALT or PINNED; never in MODE-OFF):** Make the FIRST
     line of `index.md`, each `entities/*.md`, and each `vulnerabilities/*.md`
     exactly `<!-- KB_SNAPSHOT: <SNAPSHOT_ID> -->` (substitute `CUR` from step
     0b; it is an HTML comment so it does not render). This is how the next
     pass's freshness gate (step 0b) detects drift. **MODE-OFF gate (3-state
     rule):** if `active_snapshot` is ABSENT (MODE-OFF — no `--sync` was
     requested), do NOT stamp the per-file `KB_SNAPSHOT` marker: `CUR` is the
     empty string (`arch:145`: "the empty string if `active_snapshot` was
     absent"), so the mandated marker would be `<!-- KB_SNAPSHOT:  -->` (empty
     value) — a snapshot-era artifact that did not exist in Phase 1. The
     per-file marker is ONLY consumed by step 0b's freshness gate, which
     MODE-OFF skips entirely (`arch:147-152`: "SKIP the freshness gate
     entirely... This is byte-for-byte today's behavior. Only HALT and PINNED
     run the gate below."). This MODE-OFF gate mirrors the freshness gate logic
     below and step 0b's outcome clauses, which mention per-file
     `KB_SNAPSHOT: CUR` stamping only in HALT/PINNED outcomes (CURRENT `:164`,
     scoped BUILD FRESH `:178`, full BUILD FRESH `:195`).

   - **Per-file `KB_SNAPSHOT` stamping is the sole provenance mechanism for KB
     assertions.** Do NOT write per-assertion `(AS_OF:<snapshot>)` tags — the
     `AS_OF` re-verification reader was never built, and staleness protection is
     already provided by the freshness gate (step 0b) comparing `kb_snapshot_id`
     to `SNAPSHOT_ID`, plus per-finding `discovery_commit` (enforced by
     `mantis-critic` Block B). A later-reverted fix is caught by these
     mechanisms, not by per-assertion tags.

4. **Validate and Decay Knowledge (Drift Prevention):**

   - Knowledge becomes stale when code is patched or refactored. Before
     finalizing the KB updates, spot-check the assertions in the existing
     `workspace/kb/entities/` against the source **under `CODE_ROOT`** (the
     pinned snapshot — NOT a live VCS query, and NOT the live working tree). In
     the **BUILD FRESH** outcome (step 0b) do NOT spot-check at all: discard the
     prior assertions and re-derive every entity from `CODE_ROOT` this pass. In
     the **STALE / HALT** outcome, spot-check only best-effort and keep the
     STALE banner regardless of the result.
   - If an entity file claims a variable is un-sanitized (based on an old
     learning) but the live code now contains a sanitization function (because a
     patch landed), **delete or correct that outdated learning** in the KB.
   - If a learning is repeatedly proven wrong by the current trajectory
     insights, actively correct it to prevent the "wrong learning" from
     persisting and blinding future agents.
   - When you correct or re-confirm a finding-derived assertion, re-stamp the
     `KB_SNAPSHOT` marker on that KB file.

5. **Transactional Inbox Clearing & Archiving:**

   - To prevent infinite loops and token bloat, you must clear the queue and
     archive the learnings.
   - **Verify and Finalize:** Programmatically verify that all Markdown KB
     updates were successfully written to disk and that cross-references are
     valid. Also verify, before committing, that every (re)written KB file
     BEGINS with its `<!-- KB_SNAPSHOT: <SNAPSHOT_ID> -->` marker and that every
     finding-derived verdict is grounded in the current `SNAPSHOT_ID`.
   - **Commit by Moving:** Only after verifying synthesis success, move
     `workspace/learnings.jsonl` to the archive directory:
     - Ensure the target directory exists (e.g.,
       `mkdir -p workspace/archive/learnings/`).
     - Determine the loop pass number `N` by reading `"pass_number"` from
       `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.
     - Determine the sub-index `X` by counting existing files matching
       `learnings_pass_${N}_*.jsonl` in `workspace/archive/learnings/` and
       adding 1.
     - Move the file:
       `mv workspace/learnings.jsonl workspace/archive/learnings/learnings_pass_${N}_${X}.jsonl`.
   - **Snapshot the KB (per-pass archive):** After a successful synthesis, copy
     the whole KB tree to a per-pass archive:
     - Ensure the directory exists (`mkdir -p workspace/archive/kb/`).
     - Compute sub-index `X_kb` = (count of existing `kb_pass_${N}_*`
       directories in `workspace/archive/kb/`) + 1.
     - Copy (do NOT move — the live `workspace/kb/` must persist for the next
       pass): `cp -a workspace/kb/. workspace/archive/kb/kb_pass_${N}_${X_kb}/`.
   - **Stamp state:** Write `kb_snapshot_id` = `SNAPSHOT_ID` (`CUR` from step
     0b) into `workspace/.mantis_state.json`. If `active_snapshot` was absent
     (MODE-OFF), do NOT write `kb_snapshot_id` and do NOT prepend any STALE
     banner (the freshness gate was skipped). In HALT mode, write
     `kb_snapshot_id` = `CUR` and leave the STALE banner in `index.md`.
   - If synthesis fails or is interrupted, leave `workspace/learnings.jsonl`
     intact in its original location to ensure no data is lost.
   - If `workspace/learnings.jsonl` is ABSENT on entry (e.g. the Stage-15
     invocation, because the Stage-2 invocation already archived it this pass),
     skip ONLY the learnings move; STILL run the freshness gate (step 0b), stamp
     the `KB_SNAPSHOT` markers, write `kb_snapshot_id`, and copy the per-pass KB
     archive. KB provenance must be recorded on every invocation.

When complete, notify the user.