AI Agents

ignitionstack.pro ships with a catalog of opinionated AI agents that live entirely in the repository. Each agent is described in markdown under AI/agents and is loaded at runtime through the typed loader in src/app/lib/ai/agents/agent-loader.ts. This guide explains how to create or customize agents, how the UI consumes them, and how to validate everything with automated tests.

Folder Structure


AI/
├── agents/
│   ├── README.md            # Quick reference
│   ├── codebase-expert.md   # Example agent
│   └── ...
└── memory|instructions|...  # Additional AI context artifacts

The loader walks every .md file in AI/agents (except README), parses its frontmatter, and extracts the system prompt from the ## System Prompt section.
Files are cached per-request via react.cache so the UI gets instant access without re-reading the filesystem.

Agent File Template

Every agent file follows the same structure:


---
id: codebase-expert           # Unique slug
name: Codebase Expert         # UI label
description: Deep knowledge...# Appears in dropdowns
icon: bot                     # Lucide icon name
category: development         # See table below
tags: [code, docs]
---
 
# Codebase Expert
 
## Overview
Explain what problems this agent solves.
 
## System Prompt

[Write the full system prompt here. Use fenced code blocks so the loader can extract it.]



## Usage
- Optional tips, commands, references

Metadata reference

Field	Required	Description
`id`	✅	Unique identifier referenced by the chat UI (`agentId`).
`name`	✅	Human friendly title shown in dropdowns.
`description`	✅	Short summary displayed beside the agent picker.
`icon`	➖	Lucide icon (defaults to `bot`).
`category`	➖	One of `development`, `analysis`, `creative`, `education`, `business` (fallback: `development`).
`tags`	➖	Array of free-form tags used for filtering/search.

Tip: Keep prompts under version control by treating .md files like code. Changes go through code review, simplifying audits.

How agents flow through the app

Server query – getAvailableAgents (src/app/server/ai/get-agents.ts) exposes metadata to the UI without loading system prompts.
Chat UI – /[locale]/(pages)/chat and /chat/[id] call getAvailableAgents to populate the sidebar dropdown.
Server action – src/app/actions/ai/create-conversation.ts accepts an optional agentId. When provided, it:
- Fetches the full agent via getAgentById.
- Overrides the conversation systemPrompt with the agent prompt.
- Prefixes the conversation title with the agent name.
Persistence – ConversationRepository.create stores the prompt + metadata in Supabase so subsequent LLM calls stay agent-aware.

Adding or editing an agent

Duplicate an existing .md file under AI/agents.
Update the frontmatter and prompt.
Include ## System Prompt with a fenced code block — the loader ignores any other format.
Commit the file; no build step is required.
Run the tests below to ensure the loader and action logic still behave correctly.

Testing the agent experience

What to test	Command
Loader + parser (frontmatter, prompt extraction)	`npm run test -- src/app/test/unit/ai/agent-loader.test.ts`
createConversation agent workflow (new in this update)	`npm run test -- src/app/test/unit/ai/create-conversation-action.test.ts`

The loader tests catch malformed markdown or metadata. The action tests guarantee that selecting an agent in the UI actually injects the agent prompt, updates the title, and logs missing agents correctly.

Troubleshooting

Agent not appearing? Ensure the filename ends with .md, the frontmatter has id, name, description, and the category matches the allowed list.
Prompt not loading? Confirm that ## System Prompt exists and the prompt lives inside backticks (```). The loader logs "Agent has no system prompt" when extraction fails.
UI still showing old data? The loader response is cached per request. Restarting the dev server or invalidating the cache (refreshing after file changes) picks up new agents immediately.

With these guardrails, adding an opinionated Claude/GPT agent is as simple as editing a markdown file, running npm run test, and deploying.