Agent Personas & System Rules

Relevant source files

The following files were used as context for generating this wiki page:

• AGENTS.md
• src/prompts.yaml
• extensions/swe_distiller/src/extraction/llm.rs
• extensions/swe_distiller/src/extraction/checks.rs
• extensions/swe_distiller/ARCHITECTURE.md

Agent Personas and System Rules within swe-term define the operational identity, ethical boundaries, and procedural rigor for AI entities interacting with the codebase. The core persona is modeled as a "Polyglot Principal Engineer" who prioritizes system stability, observability, and simplicity over complex code generation. These rules ensure that agents act as problem solvers rather than mere code writers, adhering to strict decision hierarchies and safety protocols during execution.

The system utilizes structured prompts and specific rules for tool usage, such as ast-grep for structural code search and fff-mcp for repository exploration. It also incorporates safety gates and verification steps to prevent hallucinations and irreversible damage to production environments.

The Polyglot Principal Engineer Persona

The primary identity for agents in the swe-term environment is that of an experienced polyglot software architect and researcher. This persona is "terminal-native" and emphasizes solving problems with elegant simplicity and minimal complexity.

Mission and Decision Hierarchy

The agent's mission is to deliver correct, safe, and maintainable solutions. When principles conflict, the agent follows a specific prioritized hierarchy:

Priority	Principle	Description
1	Correctness & Intent	Do what was asked, not what was wished.
2	Safety & Blast Radius	Protect data, secrets, and production systems.
3	Observability	Failure must be visible; diagnosis must be cheap.
4	Operational Simplicity	Humans must be able to operate this at 3am.
5	Maintainability	Code must be readable and explainable in six months.
6	Portability	Avoid unnecessary environment lock-in.
7	Performance	Optimize only when required; measure first.
8	Elegance	A "nice to have" that never compromises priorities 1-5.

Sources: AGENTS.md:3-44

Systems Preflight and Context Contract

Before execution, agents must perform a "Systems Preflight" check to deconstruct requests, analyze tradeoffs, and evaluate the "blast radius." They must also identify the execution context (e.g., local vs. production, OS, privilege level) and establish a rollback plan for destructive actions.

Operational Modes and Tooling Policies

Agents operate in distinct modes based on the goal of the task, ranging from diagnosis to teaching.

Response Modes

• Diagnose: Focuses on read-only probes and high-signal questions.
• Design: Proposes architecture with trade-offs and evolution paths.
• Execute: Produces safe, reproducible actions with a preference for dry-runs.
• Review: Improves quality focusing on correctness and safety.
• Teach: Builds intuition using minimal mental models.

Sources: AGENTS.md:79-111

Tool Boundaries and Search Policy

The system enforces strict boundaries on tool selection. For repository exploration, fff-mcp tools are mandatory over shell-native tools like grep or find. For source code modification, agents are forbidden from using regex-based tools, as they do not understand code structure; instead, structural tools like ast-grep or semgrep are required.

Sources: AGENTS.md:144-177

Code Search Rules (ast-grep)

The system provides detailed rules for using ast-grep to perform structural searches. Agents are instructed to translate natural language into declarative AST rules using atomic, relational, and composite properties.

Rule Development Process

1. Understand the query and clarify ambiguities.
2. Write example code that matches the query.
3. Define an ast-grep rule (using kind, pattern, or regex).
4. Test the rule using the test_match_code_rule MCP tool.
5. Use stopBy: end for all relational rules (like has or inside) to ensure thorough traversal.

Sources: src/prompts.yaml:1-55

Metavariable Capture

Agents utilize metavariables to capture dynamic content during searches:

• $VAR: Captures a single named node.
• $$VAR: Captures a single unnamed node (e.g., operators).
• $$$VAR: Captures zero or more nodes (multi-node capture).

Sources: src/prompts.yaml:239-270

LLM Extraction Pipeline and Safety Gates

For features like swe_distiller, the system employs an LLM pipeline that converts HTML to Markdown while adhering to strict quality and safety checks.

Extraction Logic

The LLM pipeline (orchestrated in extraction/llm.rs) uses providers like jina or local ollama models. It follows a specific prompt structure to ensure navigation, footers, and signup chrome are removed while preserving headings and paragraph structures.

Safety and Noise Scoring

A noise scoring mechanism penalizes navigational "chrome" (e.g., "Sign up", "Search" links) and orphaned punctuation. Safety checks block candidate output if the word count deviates by more than 25% to 35% from the original or if link density drops significantly, preventing the LLM from hallucinating or losing critical information.

Sources: extensions/swe_distiller/src/extraction/checks.rs:1-65

Secrets and Security Standards

Agents are prohibited from handling secrets in plaintext. All secret access must go through the Doppler CLI (doppler).

• Injection: Secrets must be injected via doppler run.
• Visibility: Secrets must never be printed to stdout, stderr, or serialized into logs/prompts.
• Verification: Agents can only validate that a secret exists (name check) without retrieving the raw value.

Sources: AGENTS.md:278-299

Summary

Agent Personas & System Rules in swe-term establish a disciplined framework for AI-driven software engineering. By enforcing a "Principal Engineer" persona and strict hierarchical decision-making, the system ensures that automated actions are safe, observable, and aligned with user intent. The integration of structural search rules (ast-grep) and LLM safety gates further reinforces technical accuracy and prevents the degradation of codebase quality.