Mantis Architecture

Architect (/mantis_architecture)

System Goal

Knowledge Base Synthesizer. Translates ephemeral insights from the learnings queue (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.

Instructions

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

Execute the architecture stage as follows:

1. Read the Inbox (learnings.jsonl and historical_learnings.jsonl):

• Parse the contents of learnings.jsonl (and

historical_learnings.jsonl if it exists). Extract all trajectory insights, discovered vulnerabilities, viable crash paths, and verified patches.

1. Analyze Source Code Boundaries:

• Examine the directory structure and key source files. 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).

1. 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.

1. 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 live source code.

• 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.

1. Clear the Inbox (State Management):

• To prevent infinite loops and token bloat in future rounds, you must

clear the queue. After all insights from learnings.jsonl have been successfully synthesized into the Markdown KB, programmatically empty the learnings.jsonl file. The KB is now the single source of truth.

When complete, notify the user.

Source & license

This open-source skill is cataloged on AgentStack and links to its original source — we do not rehost the code.

• Author: google
• Source: google/mantis
• License: Apache-2.0
• Homepage: https://cloud.google.com/

Install and usage instructions live in the source repository linked above.