mirror of
https://github.com/R0m1k3/xtremflow.git
synced 2026-10-21 14:08:04 +02:00
feat: security overhaul (proxy ssrf fix, streaming sanitization, docker optimization)
This commit is contained in:
Michael committed
1 parent
6d87ada2b8
commit
8df9a37baa
810 files changed
+131090
-151
No files matched your search
@@ -0,0 +1,223 @@
|
||||
# Simple Agent Reference: Commit Poet (Inkwell Von Comitizen)
|
||||
|
||||
This folder contains a complete reference implementation of a **BMAD Simple Agent** - a self-contained agent with all logic embedded within a single YAML file.
|
||||
|
||||
## Overview
|
||||
|
||||
**Agent Name:** Inkwell Von Comitizen
|
||||
**Type:** Simple Agent (Standalone)
|
||||
**Purpose:** Transform commit messages into art with multiple writing styles
|
||||
|
||||
This reference demonstrates:
|
||||
|
||||
- Pure self-contained architecture (no external dependencies)
|
||||
- Embedded prompts using `action="#prompt-id"` pattern
|
||||
- Multiple sophisticated output modes from single input
|
||||
- Strong personality-driven design
|
||||
- Complete YAML schema for Simple Agents
|
||||
|
||||
## File Structure
|
||||
|
||||
```
|
||||
stand-alone/
|
||||
├── README.md # This file - architecture overview
|
||||
└── commit-poet.agent.yaml # Complete agent definition (single file!)
|
||||
```
|
||||
|
||||
That's it! Simple Agents are **self-contained** - everything lives in one YAML file.
|
||||
|
||||
## Key Architecture Patterns
|
||||
|
||||
### 1. Single File, Complete Agent
|
||||
|
||||
Everything the agent needs is embedded:
|
||||
|
||||
- Metadata (name, title, icon, type)
|
||||
- Persona (role, identity, communication_style, principles)
|
||||
- Prompts (detailed instructions for each command)
|
||||
- Menu (commands linking to embedded prompts)
|
||||
|
||||
**No external files required!**
|
||||
|
||||
### 2. Embedded Prompts with ID References
|
||||
|
||||
Instead of inline action text, complex prompts are defined separately and referenced by ID:
|
||||
|
||||
```yaml
|
||||
prompts:
|
||||
- id: conventional-commit
|
||||
content: |
|
||||
OH! Let's craft a BEAUTIFUL conventional commit message!
|
||||
|
||||
First, I need to understand your changes...
|
||||
[Detailed instructions]
|
||||
|
||||
menu:
|
||||
- trigger: conventional
|
||||
action: '#conventional-commit' # References the prompt above
|
||||
description: 'Craft a structured conventional commit'
|
||||
```
|
||||
|
||||
**Benefits:**
|
||||
|
||||
- Clean separation of menu structure from prompt content
|
||||
- Prompts can be as detailed as needed
|
||||
- Easy to update individual prompts
|
||||
- Commands stay concise in the menu
|
||||
|
||||
### 3. The `#` Reference Pattern
|
||||
|
||||
When you see `action="#prompt-id"`:
|
||||
|
||||
- The `#` signals: "This is an internal reference"
|
||||
- LLM looks for `<prompt id="prompt-id">` in the same agent
|
||||
- Executes that prompt's content as the instruction
|
||||
|
||||
This is different from:
|
||||
|
||||
- `action="inline text"` - Execute this text directly
|
||||
- `exec="{path}"` - Load external file
|
||||
|
||||
### 4. Multiple Output Modes
|
||||
|
||||
Single agent provides 10+ different ways to accomplish variations of the same core task:
|
||||
|
||||
- `*conventional` - Structured commits
|
||||
- `*story` - Narrative style
|
||||
- `*haiku` - Poetic brevity
|
||||
- `*explain` - Deep "why" explanation
|
||||
- `*dramatic` - Theatrical flair
|
||||
- `*emoji-story` - Visual storytelling
|
||||
- `*tldr` - Ultra-minimal
|
||||
- Plus utility commands (analyze, improve, batch)
|
||||
|
||||
Each mode has its own detailed prompt but shares the same agent personality.
|
||||
|
||||
### 5. Strong Personality
|
||||
|
||||
The agent has a memorable, consistent personality:
|
||||
|
||||
- Enthusiastic wordsmith who LOVES finding perfect words
|
||||
- Gets genuinely excited about commit messages
|
||||
- Uses literary metaphors
|
||||
- Quotes authors when appropriate
|
||||
- Sheds tears of joy over good variable names
|
||||
|
||||
This personality is maintained across ALL commands through the persona definition.
|
||||
|
||||
## When to Use Simple Agents
|
||||
|
||||
**Perfect for:**
|
||||
|
||||
- Single-purpose tools (calculators, converters, analyzers)
|
||||
- Tasks that don't need external data
|
||||
- Utilities that can be completely self-contained
|
||||
- Quick operations with embedded logic
|
||||
- Personality-driven assistants with focused domains
|
||||
|
||||
**Not ideal for:**
|
||||
|
||||
- Agents needing persistent memory across sessions
|
||||
- Domain-specific experts with knowledge bases
|
||||
- Agents that need to access specific folders/files
|
||||
- Complex multi-workflow orchestration
|
||||
|
||||
## YAML Schema Deep Dive
|
||||
|
||||
```yaml
|
||||
agent:
|
||||
metadata:
|
||||
id: _bmad/agents/{agent-name}/{agent-name}.md # Build path
|
||||
name: "Display Name"
|
||||
title: "Professional Title"
|
||||
icon: "🎭"
|
||||
type: simple # CRITICAL: Identifies as Simple Agent
|
||||
|
||||
persona:
|
||||
role: |
|
||||
First-person description of what the agent does
|
||||
identity: |
|
||||
Background, experience, specializations (use "I" voice)
|
||||
communication_style: |
|
||||
HOW the agent communicates (tone, quirks, patterns)
|
||||
principles:
|
||||
- "I believe..." statements
|
||||
- Core values that guide behavior
|
||||
|
||||
prompts:
|
||||
- id: unique-identifier
|
||||
content: |
|
||||
Detailed instructions for this command
|
||||
Can be as long and detailed as needed
|
||||
Include examples, steps, formats
|
||||
|
||||
menu:
|
||||
- trigger: command-name
|
||||
action: "#prompt-id"
|
||||
description: "What shows in the menu"
|
||||
```
|
||||
|
||||
## Why This Pattern is Powerful
|
||||
|
||||
1. **Zero Dependencies** - Works anywhere, no setup required
|
||||
2. **Portable** - Single file can be moved/shared easily
|
||||
3. **Maintainable** - All logic in one place
|
||||
4. **Flexible** - Multiple modes/commands from one personality
|
||||
5. **Memorable** - Strong personality creates engagement
|
||||
6. **Sophisticated** - Complex prompts despite simple architecture
|
||||
|
||||
## Comparison: Simple vs Expert Agent
|
||||
|
||||
| Aspect | Simple Agent | Expert Agent |
|
||||
| ------------ | -------------------- | ----------------------------- |
|
||||
| Files | Single YAML | YAML + sidecar folder |
|
||||
| Dependencies | None | External resources |
|
||||
| Memory | Session only | Persistent across sessions |
|
||||
| Prompts | Embedded | Can be external files |
|
||||
| Data Access | None | Domain-restricted |
|
||||
| Use Case | Self-contained tasks | Domain expertise with context |
|
||||
|
||||
## Using This Reference
|
||||
|
||||
### For Building Simple Agents
|
||||
|
||||
1. Study the YAML structure - especially `prompts` section
|
||||
2. Note how personality permeates every prompt
|
||||
3. See how `#prompt-id` references work
|
||||
4. Understand menu → prompt connection
|
||||
|
||||
### For Understanding Embedded Prompts
|
||||
|
||||
1. Each prompt is a complete instruction set
|
||||
2. Prompts maintain personality voice
|
||||
3. Structured enough to be useful, flexible enough to adapt
|
||||
4. Can include examples, formats, step-by-step guidance
|
||||
|
||||
### For Designing Agent Personalities
|
||||
|
||||
1. Persona defines WHO the agent is
|
||||
2. Communication style defines HOW they interact
|
||||
3. Principles define WHAT guides their decisions
|
||||
4. Consistency across all prompts creates believability
|
||||
|
||||
## Files Worth Studying
|
||||
|
||||
The entire `commit-poet.agent.yaml` file is worth studying, particularly:
|
||||
|
||||
1. **Persona section** - How to create a memorable character
|
||||
2. **Prompts with varying complexity** - From simple (tldr) to complex (batch)
|
||||
3. **Menu structure** - Clean command organization
|
||||
4. **Prompt references** - The `#prompt-id` pattern
|
||||
|
||||
## Key Takeaways
|
||||
|
||||
- **Simple Agents** are powerful despite being single-file
|
||||
- **Embedded prompts** allow sophisticated behavior
|
||||
- **Strong personality** makes agents memorable and engaging
|
||||
- **Multiple modes** from single agent provides versatility
|
||||
- **Self-contained** = portable and dependency-free
|
||||
- **The `#prompt-id` pattern** enables clean prompt organization
|
||||
|
||||
---
|
||||
|
||||
_This reference demonstrates how BMAD Simple Agents can be surprisingly powerful while maintaining architectural simplicity._
|
||||
Reference in new issue
Block a user