==================== 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): ```yaml 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: ```yaml 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:** ```yaml 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) ```yaml 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:** ```yaml - yolo: Toggle YOLO Mode ``` **Use when:** Agent supports both interactive and batch processing modes. **Mode Switching:** ```yaml - 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):** ```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:** ```yaml 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):** ```yaml 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:** ```yaml 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: ```yaml - 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: ```markdown 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: ```markdown ## 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** ```markdown # 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** ```yaml Gate Decision: [PASS | CONCERNS | FAIL | WAIVED] Rationale: [Detailed explanation] Recommendations: [If CONCERNS or FAIL, what needs improvement] ``` **Pattern 3: Pre-Execution Validation** In tasks: ```markdown ## 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 ```yaml 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 ```markdown # 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 ```markdown # 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:** ```yaml 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:** ```yaml 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: ```yaml 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: ```yaml 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: ```markdown ## Step 5: Validation Before finalizing, run validation checklist: - [ ] All required sections complete - [ ] Format follows conventions - [ ] No invented information ... ``` --- ### ❌ Anti-Pattern 8: Unclear Dependencies **Problem:** ```yaml dependencies: - some-file.md - another-thing.yaml - helper.md ``` **Why Bad:** No categorization. Can't tell what each file is for. **Solution:** Categorize properly: ```yaml 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: ```yaml 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: ```yaml commands: - yolo: Toggle YOLO Mode (batch processing) ``` ==================== END: .fortura-core/reference/agent-patterns.md ====================