Custom System Prompt

By default, AdaL uses a general-purpose system prompt. For project-specific behavior — coding conventions, preferred libraries, deployment rules, domain context — you can provide a custom system prompt that the agent reads every turn.

There are two approaches, and they can be combined:

Method	How it works	Best for
AGENTS.md in workspace	Auto-loaded every turn from the workspace root	Shared team context committed to the repo
prompt_file option	Points to any .md file — replaces the default role prompt entirely	Per-script or per-environment overrides

AGENTS.md (Recommended)

Place an AGENTS.md file at the root of your workspace. The runtime automatically reads it every turn and injects it into the agent's context as project instructions.

my-project/
├── AGENTS.md          ← auto-loaded by the agent
├── src/
├── tests/
└── ...

Example AGENTS.md:

# Project Instructions

## Stack
- Python 3.12, FastAPI, PostgreSQL
- Frontend: React 19 + TypeScript

## Conventions
- Use `snake_case` for Python, `camelCase` for TypeScript
- All API endpoints must have OpenAPI docstrings
- Never commit `.env` files

## Testing
- Run `pytest -x` before committing
- Integration tests require `docker compose up db`

## Deployment
- Staging auto-deploys from `main`
- Production requires a tag `release-v*`

Usage

Just run AdaL in a directory that contains AGENTS.md — the agent picks it up automatically:

cd /path/to/my-project   # contains AGENTS.md
adal

Or in headless mode:

adal -q "Add a new /health endpoint with a database connectivity check." --yolo

The agent will follow the conventions defined in your AGENTS.md automatically.

Generating AGENTS.md

You can generate an initial AGENTS.md using the AdaL CLI:

cd /path/to/my-project
adal
# Then type: /init

The /init command analyzes your codebase and creates a tailored AGENTS.md.

Custom Prompt File

For cases where you need a completely different system prompt per script or environment (e.g., a security-auditor persona, a documentation writer, a test-generator), you can pass a --prompt-file flag to AdaL.

# Headless mode with a custom prompt file
adal -q "Review src/ for vulnerabilities" --prompt-file prompts/security-auditor.md --yolo

note

prompt_file replaces the default role prompt entirely. The agent will follow only the instructions in your file. AGENTS.md is still loaded as project context alongside it.

Example custom prompt file (prompts/security-auditor.md):

You are a security auditor. Your job is to find vulnerabilities in code.

## Rules
- Focus on: SQL injection, XSS, auth bypass, SSRF, path traversal
- For each finding, provide: severity (Critical/High/Medium/Low), location, and a fix
- Never modify code directly — only report findings
- Output in markdown table format

The path is resolved relative to the workspace root. Both absolute and relative paths work.

Multiple Personas in One Project

Create different prompt files for different tasks:

my-project/
├── AGENTS.md                     ← shared project context (always loaded)
├── prompts/
│   ├── security-auditor.md       ← security review persona
│   └── docs-writer.md            ← documentation writer persona
└── src/

# Security audit (read-only)
adal -q "Audit the auth module" --prompt-file prompts/security-auditor.md --enabled-default-tools "Read,Search" --yolo

# Documentation generation
adal -q "Generate API docs for src/api/" --prompt-file prompts/docs-writer.md --enabled-default-tools "Read,Edit" --yolo

Combining Both

When both AGENTS.md and --prompt-file are present:

1. --prompt-file defines the agent's role and behavior (replaces the default system prompt)
2. AGENTS.md provides project context (always injected as supplementary information)

This lets you have a stable project context (AGENTS.md) while swapping the agent's persona per task.

Tips

• Keep it concise — the system prompt consumes context window. Focus on rules the agent actually needs, not general knowledge.
• Use headings — the agent parses markdown structure, so organized sections help it find relevant rules.
• Version control AGENTS.md — it's part of your project and should evolve with it. Different branches can have different instructions.
• Test your prompt — run a few queries and verify the agent follows your custom rules before deploying in automation.