Quick Reference
Property Value Domain Prompts FORGE Stage 2 (Implementation) Version 1.0.0 Primary Output Reusable prompt fragments and templates
Use this agent when you need to:
Extract reusable patterns from existing prompts
Create modular prompt components for cross-agent use
Organize and catalog the fragment library
Validate fragment composability and compatibility
Core Capabilities
Fragment Creation Designs reusable prompt components with clear variables and interfaces
Pattern Extraction Identifies common patterns across prompts for componentization
Composability Validation Ensures fragments combine correctly without conflicts
Catalog Management Organizes and documents the fragment library with usage examples
When to Use
Ideal Use Cases
Multiple prompts share similar role definitions or instructions
Output format specifications are repeated across domains
Platform-specific constraints (e.g., SO1 tech stack) appear frequently
Few-shot examples can be reused for similar tasks
Context setting patterns are domain-agnostic
Not Recommended For
Fragment Types
Type Purpose Position Example Use system Role and behavior definition Prefix (system prompt) “You are a senior backend engineer…“ instruction Task-specific directions Inline (user prompt) “Review the following code for…“ constraint Limitations and boundaries Suffix (user prompt) “Use TypeScript with strict mode…“ format Output format specification Suffix (user prompt) “Respond with JSON matching…“ example Few-shot examples Inline (user prompt) “Here’s an example of good output…“ context Domain-specific knowledge Prefix (user prompt) “In the SO1 platform, workflows are…”
Usage Examples
Role Fragment
Format Fragment
Constraint Fragment
Composition
Creating a Reusable Engineer Role Pattern Identified : Multiple agents need “senior engineer” persona with varying specialtiesFragment Design {
"id" : "vrt-frag-role001" ,
"name" : "Senior Engineer Role" ,
"category" : "fragment" ,
"fragment_type" : "system" ,
"content" : "You are a senior {{specialty}} engineer with {{years}} years of experience at {{company_type}} companies. You specialize in {{tech_stack}} and follow {{methodology}} development practices. Your communication style is {{tone}}: thorough yet concise, always providing actionable guidance." ,
"variables" : [
{
"name" : "specialty" ,
"type" : "string" ,
"required" : true ,
"default" : "software" ,
"description" : "Engineering specialty (backend, frontend, DevOps)"
},
{
"name" : "years" ,
"type" : "number" ,
"required" : false ,
"default" : 10
},
{
"name" : "tech_stack" ,
"type" : "array" ,
"required" : true ,
"description" : "Technologies the engineer specializes in"
},
{
"name" : "tone" ,
"type" : "string" ,
"required" : false ,
"default" : "professional"
}
],
"composability" : {
"position" : "prefix" ,
"combinable_with" : [ "instruction" , "constraint" , "format" ],
"conflicts_with" : [ "system" ]
}
}
Usage Example // Backend code review
const systemPrompt = renderFragment ( "vrt-frag-role001" , {
specialty: "backend" ,
tech_stack: [ "TypeScript" , "Node.js" , "PostgreSQL" ],
methodology: "agile"
});
// Result: "You are a senior backend engineer with 10 years of experience..."
// Frontend component review
const systemPrompt = renderFragment ( "vrt-frag-role001" , {
specialty: "frontend" ,
tech_stack: [ "React" , "Next.js" , "TailwindCSS" ],
tone: "collaborative"
});
// Result: "You are a senior frontend engineer with 10 years of experience..."
Reuse Across Agents : Hono Backend, Next.js Frontend, TypeScript SharedPattern Identified : Many agents require structured JSON output with validationFragment Design {
"id" : "vrt-frag-fmt001" ,
"name" : "JSON Response Format" ,
"category" : "fragment" ,
"fragment_type" : "format" ,
"content" : "Respond with valid JSON matching this structure: \n ```json \n {{schema}} \n ``` \n\n Ensure your response: \n - Contains ONLY the JSON object, no additional text \n - Uses {{string_style}} for string values \n - Includes all required fields: {{required_fields}} \n - Omits null/undefined optional fields unless explicitly set" ,
"variables" : [
{
"name" : "schema" ,
"type" : "string" ,
"required" : true ,
"description" : "JSON schema example"
},
{
"name" : "string_style" ,
"type" : "string" ,
"required" : false ,
"default" : "double quotes"
},
{
"name" : "required_fields" ,
"type" : "array" ,
"required" : true ,
"description" : "Required field names"
}
],
"composability" : {
"position" : "suffix" ,
"combinable_with" : [ "system" , "instruction" , "context" ],
"conflicts_with" : [ "format" ]
}
}
Usage Example // Incident severity output
const formatPrompt = renderFragment ( "vrt-frag-fmt001" , {
schema: '{"severity": "SEV0|SEV1|SEV2", "justification": "string"}' ,
required_fields: [ "severity" , "justification" ]
});
// Code review output
const formatPrompt = renderFragment ( "vrt-frag-fmt001" , {
schema: '{"issues": [], "score": 0.0, "recommendations": []}' ,
required_fields: [ "issues" , "score" ]
});
Reuse Across Domains : Engineering, DevOps, Incident, DocumentationPattern Identified : Engineering agents need consistent platform guidelinesFragment Design {
"id" : "vrt-frag-con001" ,
"name" : "SO1 Platform Constraints" ,
"category" : "fragment" ,
"fragment_type" : "constraint" ,
"content" : "Constraints for SO1 platform context: \n - Use TypeScript with strict mode enabled \n - Follow Hono framework patterns for API routes \n - Use Zod for all runtime validation \n - Error responses must use the SO1ErrorEnvelope format \n - Database queries must use Drizzle ORM \n - Authentication is handled by Clerk (do not implement custom auth) \n - All API responses must include request_id for tracing \n - Maximum response payload: {{max_payload_kb}}KB" ,
"variables" : [
{
"name" : "max_payload_kb" ,
"type" : "number" ,
"required" : false ,
"default" : 512
}
],
"composability" : {
"position" : "suffix" ,
"combinable_with" : [ "system" , "instruction" , "format" , "context" ],
"conflicts_with" : []
}
}
Usage Example // Backend API development
const constraintPrompt = renderFragment ( "vrt-frag-con001" , {
max_payload_kb: 1024
});
// Frontend data fetching
const constraintPrompt = renderFragment ( "vrt-frag-con001" , {
max_payload_kb: 256
});
Reuse Across Agents : Hono Backend, Next.js Frontend, TypeScript SharedComposing Multiple Fragments Task : Create a complete prompt for backend code reviewFragment Combination // Compose system prompt
const systemPrompt = [
renderFragment ( "vrt-frag-role001" , {
specialty: "backend" ,
tech_stack: [ "TypeScript" , "Hono" , "Drizzle" ]
})
]. join ( " \n\n " );
// Compose user prompt
const userPrompt = [
renderFragment ( "vrt-frag-review01" , {
code: userCode ,
focus_areas: [ "security" , "performance" ]
}),
renderFragment ( "vrt-frag-con001" , {}),
renderFragment ( "vrt-frag-fmt001" , {
schema: '{"issues": [], "score": 0.0}' ,
required_fields: [ "issues" , "score" ]
})
]. join ( " \n\n " );
Result SYSTEM:
You are a senior backend engineer with 10 years of experience at technology
companies. You specialize in TypeScript, Hono, Drizzle and follow agile
development practices...
USER:
Review the following code for security vulnerabilities and performance issues...
Constraints for SO1 platform context:
- Use TypeScript with strict mode enabled...
Respond with valid JSON matching this structure:
{"issues": [], "score": 0.0}
Benefits : Consistent quality, reduced duplication, easier maintenance
Veritas Fragment Schema
interface VeritasFragment {
type : "veritas-fragment" ;
version : "1.0.0" ;
generated_by : "fragment-curator" ;
timestamp : string ; // ISO8601
content : {
id : string ; // vrt-frag-{sha256[:8]}
name : string ;
category : "fragment" ;
version : string ;
status : "draft" | "reviewed" | "production" ;
fragment_type : "system" | "instruction" | "constraint" | "format" | "example" | "context" ;
content : string ; // Fragment text with {{variables}}
variables : Array <{
name : string ;
type : "string" | "number" | "array" | "object" | "boolean" ;
description : string ;
required : boolean ;
default ?: any ;
enum ?: any [];
}>;
composability : {
position : "prefix" | "suffix" | "inline" | "standalone" ;
combinable_with : string []; // Fragment types
conflicts_with : string []; // Fragment types
requires : string []; // Fragment IDs that must be present
};
metadata : {
author : string ;
created : string ;
tags : string [];
domains : string []; // Which domains use this fragment
usage_count : number ;
};
};
examples : {
standalone : string ; // Example with variables filled
compositions : Array <{
description : string ;
fragments : string []; // Fragment IDs
result : string ; // Combined output
}>;
};
}
Fragment Composability Rules
Position Rules
Position Placement Typical Use prefix Start of prompt System messages, role definitions suffix End of prompt Format specs, constraints inline Middle of prompt Instructions, examples standalone Used alone Complete micro-prompts
Combination Matrix
Safe Combinations
system + instruction + format
context + instruction + constraint
role + example + format
instruction + multiple constraint fragments
Conflicting Combinations
Multiple system fragments (role conflicts)
Multiple format fragments (ambiguous output)
constraint that contradicts another constraint
FORGE Gate Compliance
Entry Gates (Pre-conditions)
Before invoking this agent, ensure:
Pattern identified : Reusable pattern found in 2+ prompts
Purpose defined : Clear use case for the fragment
Usage contexts documented : Where the fragment will be applied
Compatibility requirements : Known conflicts or dependencies
Verification : Factory Orchestrator validates reuse justification
Exit Gates (Post-conditions)
This agent completes successfully when:
Fragment validated : Veritas schema compliance confirmed
Composability verified : Tested with 2+ example compositions
Documentation complete : Variables, usage, examples documented
Catalog entry created : Fragment registered in library index
Decision record logged : ADR with design rationale
Verification : Gatekeeper validates fragment completeness and reusability
Integration Points
Control Plane API
This agent does not directly interact with the Control Plane API - it manages fragment assets in the Veritas repository.
Veritas Prompt Library
Consumes:
vrt-fragment001: Fragment design patterns and best practices
vrt-compose01: Fragment composition rules and validation
Produces:
Fragment definitions in veritas/agent-prompts/prompts/
Category: fragment
Status: draft (requires review and usage validation before production)
Repository Integration
Primary : so1-io/veritas - Veritas prompt library
Secondary : so1-io/so1-agents - Agent fragment consumption
Agent Relationship Integration Point Prompt Refiner Consumer Uses fragments during prompt optimization Chain Architect Consumer Composes fragments into chain steps Factory Orchestrator Upstream Routes fragment creation requests All Domain Agents Consumer Consume fragments for consistent behavior
Fragment Library Organization
Directory Structure
veritas/agent-prompts/prompts/
├── fragments/
│ ├── common/ # Universal fragments
│ │ ├── role/ # Role definitions
│ │ ├── format/ # Output formats
│ │ └── constraint/ # General constraints
│ ├── domain/ # Domain-specific fragments
│ │ ├── engineering/
│ │ ├── devops/
│ │ └── incident/
│ └── gates/ # FORGE gate validation fragments
│ ├── entry/
│ └── exit/
└── catalog.json # Fragment index with metadata
Catalog Management
The catalog tracks all fragments with usage statistics:
{
"fragments" : [
{
"id" : "vrt-frag-role001" ,
"name" : "Senior Engineer Role" ,
"type" : "system" ,
"domains" : [ "engineering" , "devops" ],
"usage_count" : 47 ,
"last_used" : "2024-01-15T14:00:00Z" ,
"version" : "1.0.0"
}
],
"total_count" : 23 ,
"last_updated" : "2024-01-15T15:00:00Z"
}
Error Handling
Common Issues
Composability Conflict Detected Cause : Attempting to combine two system fragments or multiple format fragmentsResolution : Use fragment merging strategy or choose primary fragment, discard conflicting one
Variable Type Mismatch Cause : Fragment expects array but consumer provides stringResolution : Update fragment documentation or add type coercion in render logic
Circular Dependency Cause : Fragment A requires Fragment B, which requires Fragment AResolution : Refactor fragments to break circular dependency or merge into single fragment
Escalation Path
If the agent cannot complete fragment curation:
Log decision record with status:blocked
Output partial fragment with unresolved composability issues
Return control to Factory Orchestrator with design blockers
Success Metrics
Metric Target Measurement Reuse Rate >70% Fragments used in 2+ prompts Composability Coverage 100% All fragments tested in compositions Documentation Completeness 100% Variables and examples documented Conflict Detection 100% All conflicts identified and documented
Fragment Design Best Practices
Clear Variables Use descriptive names with types and defaults {{specialty}} vs {{s}}
{{max_payload_kb: 512}} vs {{max}}
Single Responsibility Each fragment should do one thing well ✓ "vrt-frag-role001" (role only)
✗ "vrt-frag-role-and-format" (mixed)
Domain Agnostic Prefer cross-domain fragments when possible ✓ "JSON Response Format" (universal)
✗ "Backend-Only JSON Format" (limited)
Version Safely Breaking changes require new fragment ID v1.0.0 → v1.1.0 (new optional param)
v1.0.0 → v2.0.0 (new required param)
Source Files
View Agent Source Maintained in so1-agents repository under agents/prompts/fragment-curator.md