Unified Prompt Architecture

One Prompt Architecture.
Five Tools.
Zero Compromise.

Run promptosaurus init once. Promptosaurus generates production-grade configurations for Kilo, Cline, Claude, Copilot, and Cursor — automatically. Switch tools, swap personas, change variants. Your agents travel with you.

Deploy Now Architecture →
5
Tools
1×
Definition
0
Config Drift
∞
Scale
⚡

Configure Once

One tool-agnostic data model. Five deployment targets. No redundancy.

🎯

Persona Filtering

Team-role aware. Frontend, backend, ML — each gets exactly what they need.

⚙️

CLI-First

Init, list, switch, validate. Full pipeline control from the terminal.

🔒

Backwards Compatible

Existing configurations continue to work. Zero-migration deployment.

Capabilities

Built for production teams

Every component engineered for serious engineering organizations. No toy features, no dead weight.

📐

Configure Once, Deploy Anywhere

Tool-agnostic configuration for Agent, Skill, Workflow, Tool, Rules, and Project. The single source of truth for your entire AI configuration estate — stored in .promptosaurus.yaml.

🏗️

Builder Architecture

Five purpose-built builders transform your configuration into tool-specific outputs. BuilderFactory handles instantiation with a clean, extensible API surface.

🔍

Auto-Discovery Registry

Zero-config agent registration. The central Registry manages modes, files, and output ordering. Drop in an agent — it's automatically indexed.

👤

Persona-Based Filtering

Select your team's roles — Frontend Software Engineer, Backend Software Engineer, DevOps, QA/Tester, Data Scientist, and more — and get only the relevant agents. Universal agents are always included.

✂️

Minimal / Verbose Variants

Choose output verbosity at build time. Minimal variants cut token overhead for cost-sensitive deployments. Verbose variants retain full context for complex workflows.

🧩

Jinja2 Template Engine

Custom filters, resolvers, and template handlers built on Jinja2. Full programmatic control over rendering logic with composable template components.

⌨️

CLI Toolchain

Six production commands: init, list, switch, swap, update, validate. Complete lifecycle management from the terminal.

📦

Markdown / YAML Loader System

Loader and Parser subsystems handle Markdown and YAML ingestion. Robust parsing handles both legacy and current configuration formats without breakage.

🔄

Backwards Compatibility

Existing configurations continue to operate without modification. Adopt Promptosaurus incrementally — no forced rewrites, no big bang migrations.

Architecture

Precision-engineered data flow

From a single definition to five tool-specific outputs. Every step deterministic, auditable, and reproducible.

01

Configure Your Agents

Run promptosaurus init or edit .promptosaurus.yaml to define your agents, skills, and workflows. YAML or Markdown — both supported. One definition, no duplication.

02

CLI Invocation

Run promptosaurus init. The CLI queries the Registry to determine active mode, target tools, and persona configuration. No magic, no black boxes.

03

Persona Filtering

PersonaFilter applies team-role rules against your config. Irrelevant agents are excluded. Each persona receives a precisely scoped agent set — no noise, no bloat.

04

Builder Factory Dispatch

BuilderFactory instantiates the correct builder for each target tool. Kilo, Cline, Claude, Copilot, Cursor — each builder encapsulates its tool's specific output contract.

05

Template Engine Rendering

Jinja2 templates with custom filters and resolvers transform your config into final text. Minimal or verbose variant is applied at this stage. Output is deterministic.

06

Files Written to Disk

Builders write tool-specific files to their canonical locations: .kilo/agents/, .clinerules, .claude/, .github/instructions/, and .cursor/rules/.

Component Graph

Interactive · D3.js

Build Pipeline

Mermaid

Data Model (ERD)

Mermaid

CLI State Machine

Mermaid
Supported AI Tools

Five tools. One config.

Pick your AI coding assistant during promptosaurus init — Promptosaurus writes the right files to the right locations automatically.

Kilo IDE

Kilo IDE

Generates YAML frontmatter plus Markdown agent files for Kilo IDE. Select Kilo during promptosaurus init and all agent files are written to the .kilo/agents/ directory.

Output path: .kilo/agents/{agent_name}.md
Format: YAML frontmatter + Markdown body
Minimal and verbose variants supported
Persona-filtered agent selection
Universal agents always included
Output Preview 
---
name: code
description: Code implementation expert
variant: verbose
---

# Code Agent

You are a senior software engineer...
Cline

Cline

Generates a pure Markdown .clinerules file. Select Cline during promptosaurus init — your agent configuration is rendered into Cline's natural-language rule format automatically.

Output path: .clinerules
Format: Pure Markdown, prose-based
Natural language instruction style
Minimal and verbose variants supported
Persona-filtered agent selection
Output Preview 
# Code Agent Rules

You are a code implementation expert.

When writing tests, use_skill: testing-strategies

## Conventions
Follow the project's established patterns...
Claude

Claude

Generates the full .claude/ directory with agents, workflows, and skills as Markdown files. Select Claude during promptosaurus init to populate your entire Claude Code configuration tree.

Output path: .claude/ directory
Agents, workflows, and skills generated
Multiple files written per build
Minimal and verbose variants supported
Persona-filtered output
Output Preview 
.claude/
  agents/
    code.md
    debug.md
    backend.md
  workflows/
    code.md
  skills/
    testing-strategies.md
GitHub Copilot

GitHub Copilot

Generates YAML frontmatter + Markdown instruction files for GitHub Copilot. Select Copilot during promptosaurus init — your agent configs are written to .github/instructions/, version-controlled alongside your code.

Output path: .github/instructions/{agent}.md
Format: Markdown instructions file
GitHub-native, version-controlled
Minimal and verbose variants supported
Persona-filtered content
Output Preview 
---
applyTo: "**"
---

# Code Agent

Apply these instructions when writing
code in this repository...
Cursor

Cursor

Generates Markdown rules files for Cursor. Select Cursor during promptosaurus init — configuration is written to both .cursor/rules/ and .cursorrules, keeping Cursor in sync with your AI toolchain.

Output: .cursor/rules/ + .cursorrules
Cursor rules format compliant
Minimal and verbose variants
Per-agent file scoping
Persona-filtered content
Output Preview 
---
description: Code implementation
globs: ["**/*.py", "**/*.ts"]
---

# Code Agent

You are a senior software engineer.
Follow project conventions strictly...
Deployment

Up and running in minutes

One install command. One init. Production-grade AI agent configuration across five tools, immediately.

Bash 
pip install promptosaurus
Bash 
uv add promptosaurus
01

Install

Install via pip or uv. Promptosaurus is a pure Python package with minimal dependencies.

02

Initialize

Run promptosaurus init in your repository root. The interactive CLI guides configuration selection.

03

Deploy

Select your target tool and persona. Promptosaurus writes all configuration files to their canonical locations.

The Init Wizard

Run promptosaurus init in your project root. The interactive wizard guides you through every choice:

Bash 
$ promptosaurus init

? Which AI tool do you want to configure?
  > Kilo IDE
    Cline
    Claude
    Cursor
    GitHub Copilot

? Repository type?
  > Single-language
    Multi-language monorepo

? Prompt variant?
  > Minimal (fewer tokens)
    Verbose (full documentation)

? Select personas for your team:
  [x] Backend Software Engineer
  [ ] Frontend Software Engineer
  [x] DevOps Engineer
  [ ] QA/Tester

? Primary language?  > Python

Generating configuration for Kilo IDE...
Written: .kilo/agents/code.md
Written: .kilo/agents/debug.md
Written: .kilo/agents/backend.md
Written: .promptosaurus.yaml

Done! Your Kilo IDE configuration is ready.

Config File

This file is auto-generated by promptosaurus init. Edit it directly and run promptosaurus update to regenerate your configs — no need to re-run the interactive wizard.

YAML 
# .promptosaurus.yaml — auto-generated by `promptosaurus init`
# Edit manually and run `promptosaurus update` to regenerate

tool: kilo-ide          # kilo-ide | kilo-cli | cline | claude | cursor | copilot
variant: minimal        # minimal | verbose
repo_type: single       # single | monorepo
language: python

personas:
  - backend-software-engineer
  - qa-tester

# Run `promptosaurus update` after editing this file

CLI Reference

Six commands. Complete lifecycle coverage.

Command Description
promptosaurus init Interactive initialization. Configures target tool, active persona, and output paths. Safe to re-run.
promptosaurus list Lists all registered modes available in the current project's configuration registry.
promptosaurus switch Switches the active AI assistant tool target. Rebuilds all output files for the new target.
promptosaurus swap Swaps the active persona. Re-filters agent set and regenerates tool-specific configuration files.
promptosaurus update Updates existing configuration files with changes from the config source. Non-destructive.
promptosaurus validate Validates current configuration against the schema. Reports errors and warnings before build.
Use Cases

Production patterns

Practical CLI workflows for common Promptosaurus scenarios. Copy, adapt, run.

Kilo IDE — single backend engineer

Getting Started

Initialize Promptosaurus for a solo backend engineer targeting Kilo IDE. Only backend-relevant agents are generated.

Bash 
pip install promptosaurus
# or: uv add promptosaurus

promptosaurus init
# Tool: Kilo IDE | Type: Single-language
# Variant: Verbose | Persona: Backend Software Engineer
# → Written: .kilo/agents/code.md
# → Written: .kilo/agents/debug.md
# → Written: .kilo/agents/backend.md
# → Written: .promptosaurus.yaml

Full-stack team with Claude

Team Setup

Configure Claude for a team with multiple personas. Universal agents (ask, debug, explain, plan, orchestrator) are always included regardless of persona selection.

Bash 
promptosaurus init
# Tool: Claude | Type: Multi-language monorepo
# Variant: Minimal
# Personas: Frontend SE, Backend SE, DevOps, QA/Tester
# → Written: .claude/agents/frontend.md
# → Written: .claude/agents/backend.md
# → Written: .claude/agents/devops.md
# → Written: .claude/agents/qa.md
# → Written: .claude/agents/debug.md   ← universal
# → Written: .claude/agents/ask.md     ← universal
# → Written: .promptosaurus.yaml

Switch to a different AI tool

Tool Switch

Your team moved from Kilo to Cursor. Use promptosaurus switch — your config is preserved and regenerated for the new target.

Bash 
promptosaurus switch
# ? Which AI tool do you want to switch to?
#   > Cursor
# Regenerating for Cursor...
# Written: .cursor/rules/code.mdc
# Written: .cursor/rules/debug.mdc
# Written: .cursorrules
# Done!

Swap personas for different team

Persona Filtering

New team member is a Data Scientist. Use promptosaurus swap to update persona selection and regenerate without re-running init.

Bash 
promptosaurus swap
# ? Update persona selection:
#   [x] Backend Software Engineer
#   [x] Data Scientist        ← newly added
#   [ ] Frontend Software Engineer
# Regenerating with updated personas...
# Done!

Validate configuration in CI

Automation

Add a validation gate to your CI pipeline. Catches missing files, unregistered orphans, and config integrity issues before merging.

Bash 
promptosaurus validate
# Checking .promptosaurus.yaml...
# Checking registered agents...
# No issues found. Configuration is valid.

# GitHub Actions usage:
# - name: Validate Promptosaurus config
#   run: promptosaurus validate
Documentation

Everything you need to know

Architecture references, API documentation, builder guides, and CLI specifications.

Getting Started
Installation & Requirements Quick Start Guide CLI Reference Configuration Overview Upgrading from Legacy Config
Config Reference
Config Format Reference Agent Model Reference Skill Model Reference Workflow Model Reference Tool & Rules Models YAML vs Markdown Authoring
AI Tools
Kilo IDE Setup Cline Setup Claude Setup GitHub Copilot Setup Cursor Setup Switching Between Tools
Persona System
Persona Architecture PersonaRegistry API PersonaFilter API Defining Custom Personas Persona Filtering Logic
Template Engine
Jinja2 Integration Custom Filters Reference Template Handlers Resolvers Reference Writing Custom Templates
Registry & CLI
Registry Architecture Mode Configuration Output Ordering promptosaurus init promptosaurus validate promptosaurus switch & swap
Collaborators

Building on Promptosaurus

Want to extend Promptosaurus, add a new AI tool target, or integrate it into your own tooling? Here's everything you need.

Contribute on GitHub

Browse open issues, submit PRs, and read the contribution guide. Five builders — each a self-contained, testable unit. View on GitHub →

🏗️

Builder Architecture

Promptosaurus uses five internal builder classes: KiloBuilder, ClineBuilder, ClaudeBuilder, CopilotBuilder, CursorBuilder. Each implements a build(agent, options) interface. BuilderFactory handles instantiation.

⚙️

Python API

Call builders directly from Python scripts or build pipelines:

from promptosaurus.builders.kilo_builder import KiloBuilder
from promptosaurus.ir.models import Agent
from promptosaurus.builders.config import BuildOptions

builder = KiloBuilder()
agent = Agent(name="code", description="...",
              system_prompt="...")
output = builder.build(agent, BuildOptions(variant="verbose"))
📄

Contribution Resources