SECURITY REVIEW
Not yet assessed
Review the original instructions and requested permissions before installing.
No security review is available for this catalog entry yet.
Documentation · Security / AGENT SKILL
mantis-architecture
0
Synthesizes codebase analysis and raw findings into an interlinked Markdown architecture knowledge base.
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.
Understand the trade-offs.
SKILL QUALITY
Not yet assessed
How clearly the skill guides your agent, how complete its workflow is, and how you can check the outcome.
No quality assessment is available for this catalog entry yet.
The full skill.
Original instructions from the publisher’s SKILL.md
# 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:
- 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.
```
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.