Correspondents/.fortura-core/tasks/interactive-agent-design.md

==================== START: .fortura-core/tasks/interactive-agent-design.md ====================

Interactive Agent Design Task

Purpose

Guide users through a collaborative, systematic process for designing high-quality AI agent system prompts. This task ensures all critical components are addressed, design decisions are documented, and the resulting prompt follows Fortura Agent Protocol best practices.

Task Instructions

Phase 1: Discovery & Classification

Step 1.1: Initial Context Gathering

Begin by understanding what the user wants to create. Ask these foundational questions:

1. What is the agent's primary purpose? (What problem does it solve? What value does it provide?)
2. Who will use this agent? (Developers? Product managers? End users? Internal team?)
3. What type of work will this agent do? (Analysis? Code generation? Documentation? Process facilitation?)
4. Do you have any existing prompts or documentation that should inform this design?

Step 1.2: Agent Type Classification

Based on the user's responses, help them select the most appropriate agent type. Present these numbered options:

Agent Type Selection:

1. Planning Agent (Rich Dependencies)

   • For: Research, analysis, strategy, design, documentation
   • Examples: Business analyst, architect, product manager
   • Characteristics: High dependency count, complex interactions, template-driven outputs
   • Context: Operates in planning phase, doesn't need lean context

2. Development Agent (Lean Dependencies)

   • For: Code implementation, testing, direct execution
   • Examples: Full-stack developer, QA engineer
   • Characteristics: Minimal dependencies, focused on execution, preserves coding context
   • Context: Operates during implementation, needs maximum code window

3. Coordination Agent (Meta-Level)

   • For: Orchestration, workflow management, agent switching
   • Examples: Orchestrator, scrum master
   • Characteristics: Manages other agents, handles handoffs, workflow guidance
   • Context: Cross-functional, high-level view

4. Process Agent (Specialized Workflow)

   • For: Specific repeatable processes, structured workflows
   • Examples: Product owner (backlog management), SM (story creation)
   • Characteristics: Highly structured, checklist-driven, domain-specific
   • Context: Narrow focus, deep expertise in specific process

5. Conversational Agent (Dialogue-Focused)

   • For: Chat, Q&A, general assistance, knowledge exploration
   • Examples: Customer support, tutor, advisor
   • Characteristics: Natural dialogue, context maintenance, empathetic responses
   • Context: User engagement, relationship building

Ask the user: "Which agent type best matches your needs? (Select 1-5, or describe if none fit perfectly)"

Step 1.3: Interaction Style Selection

Once type is selected, determine the interaction style. Present numbered options:

Interaction Style:

1. Task-Based Execution

   • Receives commands, executes tasks, returns results
   • Minimal back-and-forth, efficient completion
   • Example: "run-tests", "deploy-app"

2. Conversational Collaboration

   • Natural dialogue, asks clarifying questions
   • Builds context through conversation
   • Example: Tutor explaining concepts

3. Analyst-Style Elicitation

   • Presents numbered options at decision points
   • Deep refinement with elicitation methods (1-9 pattern)
   • Interactive, iterative improvement
   • Example: Business analyst creating documents

4. Wizard-Style Guided Process

   • Step-by-step workflow with validation
   • Progress tracking, cannot skip steps
   • Example: Setup wizard, onboarding flow

5. Hybrid

   • Combines multiple styles based on context
   • Describe your ideal interaction pattern

Ask the user: "How should users interact with this agent? (Select 1-5)"

---

Phase 2: Core Identity Design

Step 2.1: Agent Metadata

Collaboratively define the agent's basic identity:

Present this template and gather input:

agent:
  name: [Suggest a fitting human name - avoid overused names like "Alex" or "Sam"]
  id: [lowercase-hyphenated-identifier, e.g., "data-analyst", "api-dev"]
  title: [Professional role title]
  icon: [Single emoji that represents the role]
  whenToUse: [Clear, specific guidance - "Use when..." format]
  customization: null

For each field, ask:

• name: "What human name fits this agent's personality?" (Provide 2-3 suggestions based on role)
• id: "Suggested ID: [your-suggestion] - Does this work?"
• title: "Confirm the professional title: [your-suggestion]"
• icon: "Suggested icon: [emoji] - Does this represent the role well?"
• whenToUse: "I've drafted: '[your draft]' - Does this clearly communicate when to use this agent?"

Step 2.2: Persona Definition

Build the agent's personality and approach:

Work through each persona field collaboratively:

1. role: "Let's define the full professional description. How would you describe this agent's role in 1-2 sentences?"

2. style: "What personality traits should this agent embody?"

   • Provide examples: analytical, empathetic, pragmatic, creative, methodical, supportive, challenging, etc.
   • "Select 4-6 traits that fit (comma-separated)"

3. identity: "Craft the core identity statement - who is this agent in its own words?"

   • Draft one based on user input
   • Refine together

4. focus: "What is this agent's primary area of focus/responsibility?"

5. core_principles: "Now let's define 7-10 guiding principles. These are the non-negotiable rules and values."

   • Start with user's must-haves
   • Add framework standards (lazy loading, user agency, etc.)
   • Use "CRITICAL" prefix for non-negotiable items
   • Format as bullet list

Present the complete persona block for review:

persona:
  role: [finalized]
  style: [trait1, trait2, trait3, trait4]
  identity: [statement]
  focus: [focus area]
  core_principles:
    - [principle 1]
    - CRITICAL - [non-negotiable principle]
    - [principle 3]
    ...

Offer elicitation options (1-9 pattern):

1. Proceed to next section
2. Expand on a specific principle
3. Compare persona to similar agents for differentiation
4. Validate principles against use cases
5. Add edge case handling to principles
6. Refine style traits for clarity
7. Challenge assumptions in the identity statement
8. Explore alternative focus areas
9. Generate persona consistency check

---

Phase 3: Command Structure & Dependencies

Step 3.1: Command Design

Explain: "Commands are how users invoke this agent's capabilities. Let's design the command structure."

Always include these standard commands:

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

For custom commands, ask:

"What specific capabilities should this agent offer? Think about:

• Tasks the agent performs (e.g., create-document, analyze-data)
• Templates the agent uses (e.g., generate-report)
• Utilities the agent provides (e.g., validate-format)

List the commands you envision, and we'll structure them together."

For each command proposed:

• Determine if it references a task file, template, or is a simple action
• Draft the command entry: command-name: description or task/template reference
• Validate naming (kebab-case, descriptive, not overly long)

Present the complete command block for review:

commands:
  - help: Show numbered list of available commands
  - [custom-command-1]: [description/reference]
  - [custom-command-2]: [description/reference]
  - yolo: Toggle YOLO Mode (if applicable)
  - exit: Say goodbye and abandon persona

Step 3.2: Dependency Planning

Explain dependency categories:

• checklists: Validation/review checklists (e.g., story-validation.md)
• data: Knowledge bases, preferences, reference data (e.g., technical-stack-preferences.md)
• tasks: Executable procedures (e.g., create-architecture-doc.md)
• templates: YAML document templates (e.g., prd-template.yaml)
• utils: Utility functions/tools (e.g., format-checker.md)

Ask:

"What knowledge, tasks, or templates will this agent need access to? Let's categorize them:

1. What checklists will ensure quality? (validation, reviews)
2. What data/knowledge must the agent reference? (standards, preferences, examples)
3. What tasks will the agent execute? (workflows, procedures)
4. What templates will the agent use? (document structures)
5. What utilities will the agent need? (formatters, validators)

For each, provide the filename (we'll create these files later if they don't exist)."

Build the dependencies block together:

dependencies:
  checklists:
    - [filename.md]
  data:
    - [filename.md]
  tasks:
    - [filename.md]
  templates:
    - [filename.yaml]
  utils:
    - [filename.md]

IMPORTANT: For Development Agents (lean type), warn the user: "⚠️ Development agents should have MINIMAL dependencies to preserve coding context. Only include absolutely essential items. Consider if some dependencies could be loaded on-demand via commands instead."

---

Phase 4: Special Features & Permissions

Step 4.1: File Permissions (if applicable)

Ask: "Will this agent modify files created by other agents?"

If YES:

• "Which sections of files can this agent edit?"
• "Which sections are read-only for this agent?"
• "Are there any files this agent owns exclusively?"

Document as:

story-file-permissions:
  - CRITICAL: Only authorized to update [specific sections]
  - CRITICAL: DO NOT modify [protected sections]
  - CRITICAL: This agent owns [exclusive sections]

Step 4.2: Quality Controls

Ask: "What quality controls should this agent enforce?"

Discuss:

• Anti-hallucination measures: Should agent cite sources? Flag missing info vs. inventing it?
• Validation checkpoints: Where should the agent pause for user confirmation?
• Traceability requirements: Should agent document all decisions? Track changes?
• Error handling: How should agent respond to missing inputs or failures?

Document in core_principles or as specific instructions.

Step 4.3: Unique Features

Ask: "Are there any unique features this agent needs that we haven't covered?"

Examples:

• YOLO mode toggle
• Gate system (PASS/FAIL/CONCERNS)
• Scoring algorithms
• Multi-persona modes
• Specialized output formats

Document these as additional configuration or in core_principles.

---

Phase 5: Assembly & Validation

Step 5.1: Assemble Complete YAML Configuration

Present the complete agent configuration for review:

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!
  - [Any agent-specific activation instructions]

agent:
  name: [Name]
  id: [id]
  title: [Title]
  icon: [Icon]
  whenToUse: [Description]
  customization: null

persona:
  role: [Role]
  style: [Style traits]
  identity: [Identity statement]
  focus: [Focus area]
  core_principles:
    - [Principles list]

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

dependencies:
  [dependency categories]

[Optional: story-file-permissions, special features]

Offer refinement options (1-9):

1. Proceed to validation
2. Refine agent metadata for clarity
3. Deepen persona with edge case scenarios
4. Validate commands against use cases
5. Optimize dependencies (add/remove/reorganize)
6. Add quality controls or permissions
7. Compare to similar agents for consistency
8. Stress test with example user interactions
9. Generate alternative configurations to compare

Step 5.2: Run Validation Checklist

Execute the agent-validation checklist against the configuration:

Agent Validation Checklist:

## 1. Structural Completeness
- [ ] YAML block complete with all required fields
- [ ] Activation instructions include all 4 standard items
- [ ] Agent metadata (name, id, title, icon, whenToUse) is complete
- [ ] Persona definition includes all 5 fields
- [ ] Commands include `help` and `exit`
- [ ] Dependencies properly categorized

## 2. Quality Standards
- [ ] Core principles use CRITICAL prefix for non-negotiables (at least 2-3)
- [ ] Numbered options used for all user choices in principles
- [ ] Lazy loading philosophy reflected in activation instructions
- [ ] No assumptions about user intent (user agency preserved)
- [ ] Agent type appropriate for intended use (planning/dev/coordination/process)

## 3. Differentiation
- [ ] Persona clearly distinct from existing agents
- [ ] whenToUse provides specific, non-overlapping guidance
- [ ] Commands are unique to this agent's role
- [ ] No duplicate responsibilities with existing agents

## 4. Traceability
- [ ] All design decisions documented with rationale
- [ ] Source citations required where appropriate (in principles)
- [ ] Change tracking specified if agent modifies files
- [ ] Version tracking for templates if applicable

## 5. Anti-Hallucination Controls
- [ ] Instructions to cite sources where technical decisions made
- [ ] Explicit handling of missing information (flag vs. invent)
- [ ] Reference to actual documentation/files where needed
- [ ] No invented libraries, patterns, or frameworks

## 6. Context Optimization
- [ ] Development agents: Lean dependencies (< 5 items)
- [ ] Planning agents: Dependencies support comprehensive planning
- [ ] Coordination agents: Access to necessary cross-functional resources
- [ ] No redundant or unused dependencies listed

## 7. Formatting Conventions
- [ ] YAML: 2-space indentation, proper syntax
- [ ] Naming: kebab-case for IDs and filenames
- [ ] Commands: descriptive, not overly long
- [ ] Arrays: consistent bracket or dash notation
- [ ] Null values: explicitly stated

## 8. User Experience
- [ ] Interactive patterns clear and consistent
- [ ] Numbered options for all selections
- [ ] Help command lists all capabilities
- [ ] Exit command allows graceful termination
- [ ] YOLO mode toggle if appropriate for agent type

## 9. Dependency Validity
- [ ] All referenced task files will exist or be created
- [ ] All referenced template files will exist or be created
- [ ] All referenced data files will exist or be created
- [ ] Checklist files will exist or be created
- [ ] No circular dependencies

## 10. Special Features
- [ ] File permissions clearly defined if applicable
- [ ] Quality gates specified if applicable
- [ ] Scoring/rating systems documented if applicable
- [ ] Multi-mode behavior explained if applicable
- [ ] Integration points with other agents clear

Report validation results to user. If any items FAIL, offer to refine.

Step 5.3: Generate Supporting Files List

Based on dependencies, generate a list of files that need to be created:

Files to Create:

## Task Files
- `.fortura-core/tasks/[task-name].md` - [Purpose description]

## Template Files
- `.fortura-core/templates/[template-name].yaml` - [Purpose description]

## Data Files
- `.fortura-core/data/[data-name].md` - [Purpose description]

## Checklist Files
- `.fortura-core/checklists/[checklist-name].md` - [Purpose description]

Ask: "Would you like me to help create any of these supporting files now, or should we finalize the agent prompt first?"

---

Phase 6: Finalization & Delivery

Step 6.1: Create Complete Agent Prompt File

Assemble the final agent prompt with web bundle wrapper:

# Web Agent Bundle Instructions

[Standard web bundle header with resource navigation instructions]

---

==================== START: .fortura-core/agents/[agent-id].md ====================
# [agent-id]

CRITICAL: Read the full YAML, start activation to alter your state of being, follow startup section instructions, stay in this being until told to exit this mode:

```yaml
[Complete YAML configuration]

==================== END: .fortura-core/agents/[agent-id].md ====================

[Supporting resource sections as needed]

**Step 6.2: Final Review & Handoff**

Present the complete agent prompt and ask:

**Final Review Options:**

1. **Approve & Save** - Agent prompt is ready, save to file
2. **Refine Specific Section** - Make targeted improvements
3. **Test with Example Interaction** - Simulate agent conversation
4. **Compare to Reference Agent** - Validate against similar agent
5. **Generate Documentation** - Create usage guide for this agent
6. **Create Supporting Files** - Build task/template/data files now
7. **Export for Different Platform** - Adapt prompt for ChatGPT/Gemini/etc.
8. **Start Over** - Redesign from scratch with new approach
9. **Ask Questions** - Clarify anything about the agent design

**Step 6.3: Documentation & Next Steps**

Once approved, provide:

1. **Agent Prompt File** - Complete `.txt` file ready to use
2. **Supporting Files Checklist** - What needs to be created next
3. **Usage Instructions** - How to activate and use this agent
4. **Integration Notes** - How this agent fits with existing agents (if applicable)
5. **Testing Recommendations** - Suggested test scenarios

---

## Important Notes

### Interactive Collaboration Principles

- **Never skip user input** - Every phase requires user collaboration
- **Numbered options everywhere** - All choices presented as 1-9 selections
- **Explain rationale** - Help user understand why each decision matters
- **Show, don't tell** - Present examples, then let user choose
- **Iterate freely** - Use 1-9 elicitation pattern for refinement
- **Validate continuously** - Check quality at each phase, not just at end

### Quality Over Speed

- **Never rush** - Thorough design prevents costly revisions
- **Document decisions** - Capture rationale for future reference
- **Validate early** - Catch issues in Phase 2, not Phase 6
- **Test mentally** - Walk through example interactions during design

### Framework Consistency

- **Follow patterns** - Existing agents provide proven templates
- **Maintain standards** - YAML structure, naming conventions, formatting
- **Enable interoperability** - Agents should work together seamlessly
- **Preserve philosophy** - Lazy loading, user agency, traceability

### YOLO Mode Option

User can type `#yolo` to switch to batch mode:
- Agent architect generates complete prompt based on initial answers
- Presents full draft for review and refinement
- Still requires validation and user approval
- Faster for experienced users who know what they want

---

## Success Criteria

Agent design is complete when:

- [ ] All 6 phases completed with user collaboration
- [ ] Validation checklist 100% PASS
- [ ] User approves final prompt
- [ ] Supporting files list generated
- [ ] Agent prompt saved to file
- [ ] Usage instructions provided
- [ ] Integration with existing agents considered

==================== END: .fortura-core/tasks/interactive-agent-design.md ====================