Skip to main content

Quick Reference

PropertyValue
DomainPrompts
FORGE Stage2 (Implementation)
Version1.0.0
Primary OutputReusable 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

Fragment Types

TypePurposePositionExample Use
systemRole and behavior definitionPrefix (system prompt)“You are a senior backend engineer…“
instructionTask-specific directionsInline (user prompt)“Review the following code for…“
constraintLimitations and boundariesSuffix (user prompt)“Use TypeScript with strict mode…“
formatOutput format specificationSuffix (user prompt)“Respond with JSON matching…“
exampleFew-shot examplesInline (user prompt)“Here’s an example of good output…“
contextDomain-specific knowledgePrefix (user prompt)“In the SO1 platform, workflows are…”

Usage Examples

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 Shared

Output Format

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

PositionPlacementTypical Use
prefixStart of promptSystem messages, role definitions
suffixEnd of promptFormat specs, constraints
inlineMiddle of promptInstructions, examples
standaloneUsed aloneComplete 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

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
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
All significant fragment design decisions are logged as:
date:2024-01-15T14:00:00Z|context:Creating reusable role fragment for engineering agents|decision:Made tech_stack parameter array type instead of string|rationale:Engineers typically specialize in multiple technologies, array allows proper listing|consequences:Agents can specify multiple technologies without string parsing|status:accepted

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
AgentRelationshipIntegration Point
Prompt RefinerConsumerUses fragments during prompt optimization
Chain ArchitectConsumerComposes fragments into chain steps
Factory OrchestratorUpstreamRoutes fragment creation requests
All Domain AgentsConsumerConsume 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 DetectedCause: Attempting to combine two system fragments or multiple format fragmentsResolution: Use fragment merging strategy or choose primary fragment, discard conflicting one
Variable Type MismatchCause: Fragment expects array but consumer provides stringResolution: Update fragment documentation or add type coercion in render logic
Circular DependencyCause: 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:
  1. Log decision record with status:blocked
  2. Output partial fragment with unresolved composability issues
  3. Return control to Factory Orchestrator with design blockers

Success Metrics

MetricTargetMeasurement
Reuse Rate>70%Fragments used in 2+ prompts
Composability Coverage100%All fragments tested in compositions
Documentation Completeness100%Variables and examples documented
Conflict Detection100%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