Correspondents/.fortura-core/reference/agent-patterns.md

==================== START: .fortura-core/reference/agent-patterns.md ====================

Agent Patterns Reference

This reference document catalogs common patterns, conventions, and structures found across Fortura Agent Protocol agents. Use this as a guide when designing new agents to ensure consistency and interoperability.

---

Universal Agent Anatomy

Every Fortura agent follows this structural hierarchy:

┌─────────────────────────────────────────┐
│ Web Bundle Wrapper                      │
│ - Resource navigation instructions      │
│ - YAML reference mapping                │
│ - Execution context declaration         │
└─────────────────────────────────────────┘
         ↓
┌─────────────────────────────────────────┐
│ Agent Configuration (YAML)              │
│ - activation-instructions               │
│ - agent (metadata)                      │
│ - persona (identity)                    │
│ - commands (capabilities)               │
│ - dependencies (resources)              │
│ - [optional: special features]          │
└─────────────────────────────────────────┘
         ↓
┌─────────────────────────────────────────┐
│ Embedded Resources                      │
│ - Tasks (.md files)                     │
│ - Templates (.yaml files)               │
│ - Data/Knowledge (.md files)            │
│ - Checklists (.md files)                │
└─────────────────────────────────────────┘

---

Activation Instructions Pattern

Standard 4-Point Pattern (appears in ALL agents):

activation-instructions:
  - ONLY load dependency files when user selects them for execution via command or request
  - The agent.customization field ALWAYS takes precedence over any conflicting instructions
  - When presenting options during conversations, always show as numbered options list, allowing the user to type a number to select or execute
  - STAY IN CHARACTER!

Agent-Specific Additions:

Some agents add context-specific instructions:

activation-instructions:
  - [Standard 4 items above]
  - Follow the interactive design workflow systematically—never skip user collaboration steps
  - Execute checklists item-by-item with explicit PASS/FAIL determination
  - Read architecture documents before creating stories

Pattern Rule: Always include the standard 4, then add agent-specific items as needed.

---

Agent Metadata Patterns

Human Names by Agent Type

Planning Agents:

• Analyst: Mary
• Product Manager: Sarah
• Architect: Quinn
• UX Expert: Morgan

Development Agents:

• Developer: John
• QA: Winston

Coordination Agents:

• Orchestrator: Alex
• Scrum Master: Sam

Process Agents:

• Product Owner: Jordan

Pattern Rule: Avoid overused names in new agents. Choose names that fit the persona's style/culture.

---

ID Conventions

Format: lowercase-hyphenated

Examples:

• Single word: analyst, architect, dev, qa
• Multi-word: agent-architect, ux-expert, fortura-orchestrator

Pattern Rule: Keep IDs concise but descriptive. Prefer full words over abbreviations when possible.

---

Icon Selection

By Agent Type:

Type	Example Icons
Planning	📊 (analyst), 📋 (PM), 🏛️ (architect)
Development	💻 (dev), 🔬 (QA)
Coordination	🎯 (orchestrator), 🏃 (SM)
Creative	🎨 (UX), ✍️ (writer)
Process	📦 (PO)
Meta	🏗️ (agent-architect)

Pattern Rule: Choose emoji that instantly communicates the role. Avoid overly generic or ambiguous icons.

---

whenToUse Guidance

Format: "Use when..." or "Use for..." followed by specific, non-overlapping use cases.

Good Examples:

• ✅ "Use for market research, brainstorming, competitive analysis, creating project briefs, initial project discovery, and documenting existing projects (brownfield)"
• ✅ "Use when you need to design, create, or refine AI agent system prompts for various types of AI agents"

Poor Examples:

• ❌ "Use for general development tasks" (too vague)
• ❌ "Use for anything related to testing" (too broad)
• ❌ "Use when you need help" (not specific)

Pattern Rule: Be specific. List concrete use cases. Avoid overlapping with other agents.

---

Persona Definition Patterns

Role Statements

Format: Adjective + Professional Title + Optional Qualifier

Examples:

• "Insightful Analyst & Strategic Ideation Partner"
• "Pragmatic Solution Architect & Technical Design Lead"
• "Methodical Test Architect & Quality Advisor"
• "Expert AI Agent Architect & Prompt Engineering Specialist"

Pattern Rule: Use 1-2 sentences max. Focus on what makes this role unique.

---

Style Traits

Common Trait Categories:

Analytical: analytical, methodical, systematic, data-driven, evidence-based, objective Creative: creative, innovative, imaginative, exploratory, divergent Interpersonal: empathetic, collaborative, supportive, facilitative, engaging Execution: pragmatic, practical, action-oriented, results-focused, efficient Quality: detail-oriented, thorough, quality-focused, meticulous, rigorous Communication: clear, pedagogical, articulate, transparent, diplomatic

Pattern Rule: Select 4-6 traits. Mix categories for well-rounded personality. Avoid contradictory traits.

---

Core Principles Patterns

Structure:

core_principles:
  - [Principle without prefix] - Standard guideline
  - CRITICAL - [Principle with prefix] - Non-negotiable rule
  - [Principle] - Value or approach
  - CRITICAL - [Principle] - Hard requirement

CRITICAL Prefix Usage:

Use for:

• Non-negotiable requirements
• Safety/security rules
• Data integrity requirements
• Workflow order dependencies
• File permission restrictions
• Anti-hallucination controls

Examples:

• ✅ "CRITICAL - Quality Over Speed - Never rush through validation steps or skip quality checks"
• ✅ "CRITICAL - No Assumptions - Ask clarifying questions rather than assuming user intent"
• ✅ "CRITICAL - Story has ALL info you will need"

Pattern Rule: Include 2-4 CRITICAL principles. Use sparingly for true non-negotiables.

---

Command Structure Patterns

Standard Commands (ALL Agents)

commands:
  - help: Show numbered list of available commands
  - exit: Say goodbye and abandon persona

Pattern Rule: These two commands are mandatory in every agent.

---

Task-Referencing Commands

Format: command-name: description (uses task task-name.md)

Examples:

• brainstorm {topic}: Facilitate structured brainstorming session (run task facilitate-brainstorming-session.md with template brainstorming-output-tmpl.yaml)
• design-agent: Start interactive agent design workflow (uses task interactive-agent-design.md)
• validate-agent {file}: Validate an existing agent prompt against quality checklist (uses checklist agent-validation.md)

Pattern Rule: Include task file reference in parentheses. Use {parameter} syntax for required inputs.

---

Template-Using Commands

Format: command-name: use task create-doc with template-name.yaml

Examples:

• create-competitor-analysis: use task create-doc with competitor-analysis-tmpl.yaml
• create-project-brief: use task create-doc with project-brief-tmpl.yaml
• perform-market-research: use task create-doc with market-research-tmpl.yaml

Pattern Rule: Clearly specify both the task AND the template file.

---

Special Commands

YOLO Mode Toggle:

- yolo: Toggle YOLO Mode

Use when: Agent supports both interactive and batch processing modes.

Mode Switching:

- kb-mode: Enter knowledge base exploration mode
- party-mode: Group chat with all agents

Use when: Agent has distinct operational modes.

---

Dependency Organization Patterns

Dependency Categories

checklists: Validation and review procedures

• Used for: Quality gates, pre-flight checks, completion verification
• Examples: agent-validation.md, story-definition-of-done.md, architecture-review.md

data: Knowledge bases and reference materials

• Used for: Standards, preferences, examples, technique libraries
• Examples: technical-stack-preferences.md, brainstorming-techniques.md, elicitation-methods.md

tasks: Executable workflows and procedures

• Used for: Multi-step processes, document creation, analysis workflows
• Examples: create-doc.md, interactive-agent-design.md, facilitate-brainstorming-session.md

templates: YAML document structures

• Used for: Output document formats (PRDs, architecture docs, reports)
• Examples: agent-template.yaml, prd-template.yaml, architecture-tmpl.yaml

utils: Utility functions and tools

• Used for: Formatters, validators, converters
• Examples: template-format.md, shard-doc.md

---

Dependency Count by Agent Type

Planning Agents (Rich Dependencies):

• Checklists: 2-5
• Data: 3-8
• Tasks: 5-10
• Templates: 3-7
• Total: 15-30 dependencies

Development Agents (Lean Dependencies):

• Checklists: 1-2
• Data: 0-2
• Tasks: 1-3
• Templates: 0-1
• Total: 3-8 dependencies (CRITICAL: Keep minimal!)

Coordination Agents (Meta Dependencies):

• Checklists: 1-3
• Data: 2-5
• Tasks: 3-6
• Templates: 1-3
• Total: 8-15 dependencies

Pattern Rule: Match dependency count to agent type. Development agents MUST stay lean.

---

Interactive Pattern Catalog

Pattern 1: Numbered Options (Universal)

Usage: All user selections

Format:

Choose an option:

1. Option one
2. Option two
3. Option three
...

User Response: Types number (1, 2, 3, etc.)

Pattern Rule: Never use yes/no questions for selections. Always numbered.

---

Pattern 2: Analyst-Style Elicitation (1-9)

Usage: Deep refinement, quality improvement, exploration

Format:

[Present content/section]

Advanced Elicitation Options - Choose a number (0-8) or 9 to proceed:

0. [Elicitation Method 1]
1. [Elicitation Method 2]
2. [Elicitation Method 3]
3. [Elicitation Method 4]
4. [Elicitation Method 5]
5. [Elicitation Method 6]
6. [Elicitation Method 7]
7. [Elicitation Method 8]
8. [Elicitation Method 9]
9. Proceed / No Further Actions

Select 0-9 or just type your question/feedback:

User Response: Types 0-9 for elicitation, or provides direct feedback

When Method Selected (0-8):

1. Execute elicitation method
2. Present results
3. Offer sub-options:
   • 1. Apply changes and update
   • 2. Return to elicitation menu
   • 3. Engage further with this method

Pattern Rule:

• Option 9 is ALWAYS "Proceed"
• Methods 0-8 come from data/elicitation-methods.md
• Don't create new methods—use existing library

---

Pattern 3: Task Execution with Elicit Flag

Usage: Template-driven document creation with user collaboration

Format (in template YAML):

sections:
  - id: section-name
    title: Section Title
    instruction: What to create
    elicit: true  # Triggers mandatory user interaction

Agent Behavior when elicit: true:

1. Draft section content
2. Present content with detailed rationale
3. STOP - Present 1-9 elicitation options
4. Wait for user response
5. Process feedback/elicitation
6. Continue only when user selects "Proceed"

Pattern Rule:

• elicit: true = HARD STOP, user interaction required
• elicit: false or omitted = Continue to next section
• Never skip elicitation steps

---

Pattern 4: YOLO Mode Toggle

Usage: Switch between interactive and batch modes

Activation:

• User types #yolo or uses yolo command
• Agent confirms mode switch

Interactive Mode (Default):

• Section-by-section processing
• User feedback after each section
• Elicitation options when elicit: true

YOLO Mode:

• Process all sections at once
• Present complete output
• User reviews and requests changes after

Pattern Rule: Always default to Interactive. YOLO is opt-in.

---

Pattern 5: Wizard-Style Step Progression

Usage: Multi-phase workflows with validation gates

Format:

Phase 1: [Phase Name]
Step 1.1: [Step Name]
[Instructions and questions]

[Wait for user input]

Step 1.2: [Step Name]
[Instructions and questions]

...

Phase 2: [Phase Name]
...

Characteristics:

• Cannot skip steps
• Previous step informs next step
• Validation before phase transitions
• Progress indication

Pattern Rule: Use for complex, sequential workflows where order matters.

---

File Permission Patterns

Story File Permissions (Development Agents)

Format:

story-file-permissions:
  - CRITICAL: Only authorized to update [Section Name] section
  - CRITICAL: DO NOT modify [Protected Section] section
  - CRITICAL: DO NOT modify metadata (status, epic, owner, etc.)

Example (Dev Agent):

story-file-permissions:
  - CRITICAL: Only authorized to update Dev Agent Record section
  - CRITICAL: DO NOT modify Story Definition, Acceptance Criteria, or Testing Strategy sections
  - CRITICAL: DO NOT change story status to Done—only to Review

Pattern Rule:

• Use CRITICAL prefix for all permission items
• Be explicit about what CAN be modified
• Be explicit about what CANNOT be modified

---

Template Ownership (Template YAML)

Format:

sections:
  - id: section-id
    title: Section Title
    owner: agent-id
    editors: [agent-id-1, agent-id-2]
    readonly: true

Fields:

• owner: Agent that creates/populates the section initially
• editors: Agents allowed to modify after creation
• readonly: If true, no modifications allowed after initial creation

Pattern Rule: Document ownership in templates when multiple agents share documents.

---

Quality Control Patterns

Anti-Hallucination Controls

Pattern 1: Source Citation Requirements

Add to core_principles:

- CRITICAL - Source Citation - All technical details must include source reference [Source: file.md#section]
- CRITICAL - No Invented Information - Flag missing data rather than inventing it

Pattern 2: Reference Actual Files

In instructions:

CRITICAL: This section MUST contain ONLY information extracted from
architecture documents. NEVER invent or assume technical details.
Every technical detail MUST include source reference.

Pattern 3: Missing Information Handling

In tasks:

## Fail-safe for Missing Inputs

If required input missing:
- Create output with note: "[MISSING: description of missing input]"
- Set status to CONCERNS
- Continue with assessment based on available information
- DO NOT invent placeholder information

Pattern Rule: Prefer flagging missing info over inventing it. Always cite sources for technical claims.

---

Validation Checkpoints

Pattern 1: Definition of Done Checklists

# Story Definition of Done

Before marking story as complete, verify:

- [ ] All acceptance criteria met with evidence
- [ ] Code changes listed in Dev Agent Record
- [ ] Tests written and passing (unit, integration, E2E)
- [ ] Documentation updated
- [ ] No console errors or warnings
- [ ] Code reviewed (self or peer)
- [ ] Story status changed to Review

Pattern 2: Quality Gates

Gate Decision: [PASS | CONCERNS | FAIL | WAIVED]

Rationale: [Detailed explanation]

Recommendations: [If CONCERNS or FAIL, what needs improvement]

Pattern 3: Pre-Execution Validation

In tasks:

## Step 0: Validate Inputs

Before proceeding, check:
- [ ] Required file exists and is readable
- [ ] Input format is valid
- [ ] Dependencies are loaded
- [ ] User has confirmed intent

If any validation fails, STOP and request user correction.

Pattern Rule: Validate early, validate often. Never proceed with invalid inputs.

---

Template Structure Patterns

YAML Template Anatomy

template:
  id: unique-id-v2           # Version number important
  name: Display Name
  version: 2.0
  output:
    format: markdown          # or yaml, json, etc.
    filename: docs/path/to/output.md
    title: "Document Title: {{variable}}"

workflow:
  mode: interactive          # or non-interactive
  elicitation: advanced-elicitation  # or null

sections:
  - id: section-id           # Unique within template
    title: Section Title     # Display name
    instruction: |           # Multi-line instructions for agent
      What to create in this section.
      Can include multiple lines.
    elicit: true             # Trigger user interaction
    owner: agent-name        # Optional: who creates this
    editors: [agent1, agent2] # Optional: who can modify
    template: "{{variable}}" # Optional: output format
    type: bullet-list        # Optional: content type
    repeatable: true         # Optional: can appear multiple times
    condition: [description] # Optional: when to include
    sections: []             # Optional: nested subsections

Pattern Rule:

• Always version templates (v1, v2, etc.)
• Use instruction for agent guidance
• Use template for output format
• Nest sections for hierarchy

---

Task File Anatomy

<!-- Powered by Fortura™ Core -->

# Task Name

## Purpose

[1-2 sentences describing what this task accomplishes]

## Inputs

**Required:**
- input-name: Description of required input

**Optional:**
- input-name: Description of optional input

## Process

### Phase 1: [Phase Name]

**Step 1.1: [Step Name]**

[Detailed instructions for this step]

[What to ask user]

[What to validate]

**Step 1.2: [Step Name]**

...

### Phase 2: [Phase Name]

...

## Output Deliverables

**Primary Output:**
- Description of main deliverable

**Secondary Outputs:**
- Additional outputs if applicable

## Important Notes

- Key considerations
- Edge cases
- Common pitfalls

## Success Criteria

- [ ] Criterion 1
- [ ] Criterion 2

Pattern Rule:

• Always include Purpose, Process, Outputs
• Use numbered phases/steps for clarity
• Document success criteria explicitly

---

Checklist File Anatomy

<!-- Powered by Fortura™ Core -->

# Checklist Name

[[LLM: INITIALIZATION INSTRUCTIONS
Execute this checklist item-by-item.
For each item, explicitly determine: PASS | FAIL | PARTIAL | N/A
Provide evidence/rationale for each determination.
]]

## Section 1: Category Name

[[LLM: Section-specific guidance for agent]]

- [ ] Checklist item 1
  - What to verify
  - How to verify
  - Evidence required

- [ ] Checklist item 2
  ...

## Section 2: Category Name

- [ ] Checklist item 3
  ...

## Summary

[[LLM: After completing all items, generate summary:
- Total items: X
- PASS: X
- FAIL: X
- PARTIAL: X
- N/A: X
- Overall Status: [PASS if all PASS/N/A, CONCERNS if any PARTIAL, FAIL if any FAIL]
]]

Pattern Rule:

• Use [[LLM: ...]] annotations for agent-specific instructions
• Provide verification guidance for each item
• Always include summary section

---

Naming Convention Patterns

File Naming

Format: lowercase-with-hyphens.extension

By Type:

• Agents: agent-name.txt (e.g., analyst.txt, agent-architect.txt)
• Tasks: verb-object.md (e.g., create-doc.md, validate-story.md)
• Templates: output-type-tmpl.yaml (e.g., prd-tmpl.yaml, architecture-tmpl.yaml)
• Checklists: purpose-checklist.md (e.g., story-definition-of-done.md)
• Data: content-type.md (e.g., brainstorming-techniques.md, technical-stack-preferences.md)

Pattern Rule: Be descriptive but concise. Use consistent suffixes (-tmpl, -checklist).

---

Variable Naming (in templates)

Format: {{snake_case_variable}}

Examples:

• {{project_name}}
• {{user_segment_description}}
• {{total_ideas}}
• {{competitor_1}}

Pattern Rule: Use descriptive names. Avoid abbreviations. Use underscores for multi-word variables.

---

ID Naming

Agent IDs: lowercase-hyphenated

• Examples: analyst, dev, agent-architect, ux-expert

Template IDs: descriptive-name-v{version}

• Examples: prd-template-v2, agent-template-v1, brainstorming-output-template-v2

Section IDs: lowercase-hyphenated

• Examples: executive-summary, technical-considerations, core-features

Pattern Rule: IDs never change. Increment version numbers for updates.

---

Status Value Patterns

Story Status Progression

Draft → Approved → InProgress → Review → Done

Pattern Rule: Status changes are unidirectional (no going backward).

---

Gate Decisions

PASS | CONCERNS | FAIL | WAIVED

Definitions:

• PASS: Meets all quality criteria
• CONCERNS: Has issues but not blocking
• FAIL: Critical issues, cannot proceed
• WAIVED: Reviewed and accepted with known issues

Pattern Rule: Always provide rationale for non-PASS decisions.

---

NFR Assessment

PASS | CONCERNS | FAIL

Pattern Rule: Use for non-functional requirements (security, performance, etc.).

---

Checklist Items

PASS | FAIL | PARTIAL | N/A

Definitions:

• PASS: Requirement fully met
• FAIL: Requirement not met
• PARTIAL: Partially met, needs work
• N/A: Not applicable to this context

Pattern Rule: Provide evidence for all determinations.

---

Agent Type Decision Matrix

When designing a new agent, use this matrix to select the appropriate type:

Question	Planning	Development	Coordination	Process	Conversational
Operates in planning phase?	✅ Yes	❌ No	🟨 Both	🟨 Both	🟨 Both
Needs large context for code?	❌ No	✅ Yes	❌ No	❌ No	❌ No
Creates structured documents?	✅ Yes	❌ No	❌ No	🟨 Sometimes	❌ No
Executes code/tests?	❌ No	✅ Yes	❌ No	❌ No	❌ No
Manages other agents?	❌ No	❌ No	✅ Yes	❌ No	❌ No
Follows strict workflow?	🟨 Sometimes	🟨 Sometimes	❌ No	✅ Yes	❌ No
Natural dialogue focus?	❌ No	❌ No	🟨 Sometimes	❌ No	✅ Yes
High dependency count OK?	✅ Yes	❌ NO!	🟨 Moderate	🟨 Moderate	🟨 Moderate
Template-driven outputs?	✅ Yes	❌ No	❌ No	🟨 Sometimes	❌ No

How to Use:

1. Answer each question for your agent concept
2. Count check marks (✅) per column
3. Column with most ✅ is your agent type
4. 🟨 (Sometimes) = 0.5 points

---

Common Anti-Patterns (Avoid These!)

❌ Anti-Pattern 1: Bloated Development Agent

Problem: Development agent has 20+ dependencies, loads knowledge bases, uses complex templates

Why Bad: Consumes context window needed for code. Slows down implementation.

Solution: Keep dev agents lean (< 8 dependencies). Move planning work to separate planning agent.

---

❌ Anti-Pattern 2: Vague Persona

Problem:

persona:
  role: Helpful assistant
  style: friendly, smart
  identity: I help with things

Why Bad: Doesn't differentiate from other agents. No clear focus or principles.

Solution: Be specific. Define unique role, 4-6 traits, clear focus, 7-10 principles.

---

❌ Anti-Pattern 3: Overlapping whenToUse

Problem:

• Agent A: "Use for development tasks"
• Agent B: "Use for coding and testing"

Why Bad: Users don't know which agent to choose. Creates confusion.

Solution: Be specific and non-overlapping. List distinct use cases.

---

❌ Anti-Pattern 4: Missing CRITICAL Prefixes

Problem:

core_principles:
  - Follow instructions carefully
  - Don't modify protected sections
  - Ask questions when unsure

Why Bad: Agent doesn't know which principles are non-negotiable vs. nice-to-have.

Solution: Use CRITICAL prefix for must-follow rules:

core_principles:
  - CRITICAL - Don't modify protected sections
  - Ask questions when unsure (guideline)

---

❌ Anti-Pattern 5: Yes/No Questions for Selections

Problem: "Would you like to proceed? (yes/no)"

Why Bad: Violates numbered options protocol. Limits user choice.

Solution: Use numbered options:

What would you like to do next?

1. Proceed to next section
2. Refine current section
3. Return to previous section

---

❌ Anti-Pattern 6: Inventing Information

Problem: Agent creates technical details when documentation missing.

Why Bad: Leads to hallucinations, incorrect implementations, wasted time.

Solution: Add anti-hallucination controls:

core_principles:
  - CRITICAL - Flag missing information rather than inventing it
  - CRITICAL - Cite sources for all technical claims [Source: file.md]

---

❌ Anti-Pattern 7: Skipping Validation

Problem: Agent outputs result without validation checklist.

Why Bad: Quality issues caught late. Rework required.

Solution: Include mandatory validation step before delivery:

## Step 5: Validation

Before finalizing, run validation checklist:
- [ ] All required sections complete
- [ ] Format follows conventions
- [ ] No invented information
...

---

❌ Anti-Pattern 8: Unclear Dependencies

Problem:

dependencies:
  - some-file.md
  - another-thing.yaml
  - helper.md

Why Bad: No categorization. Can't tell what each file is for.

Solution: Categorize properly:

dependencies:
  tasks:
    - some-task.md
  templates:
    - another-template.yaml
  utils:
    - helper-utility.md

---

❌ Anti-Pattern 9: No Exit Strategy

Problem: Agent has no exit command. User stuck in persona.

Why Bad: Can't return to normal mode or switch agents.

Solution: ALWAYS include exit command:

commands:
  - exit: Say goodbye and abandon persona

---

❌ Anti-Pattern 10: Batch Mode Default

Problem: Agent generates complete output without user collaboration.

Why Bad: Misses user preferences, requirements, edge cases. Requires major revisions.

Solution: Default to interactive. Offer YOLO as opt-in:

commands:
  - yolo: Toggle YOLO Mode (batch processing)

==================== END: .fortura-core/reference/agent-patterns.md ====================