@vibe-agent-toolkit/vat-example-cat-agents 0.2.0-rc.6 → 0.2.0-rc.8

package/dist/skills/vat-example-cat-agents/resources/cat-breed-selection.md

@@ -0,0 +1,233 @@
+# Cat Breed Selection Skill
+
+Guide for Claude Code to help users select cat breeds through conversational interaction.
+
+## Purpose: For Claude Code, Not the LLM
+
+**Key distinction:**
+- **This file** = Guidance for Claude Code (how to orchestrate)
+- **Agent resources** = Content for the LLM (what to say/know)
+
+This skill references agent resources via markdown links but doesn't duplicate LLM prompts.
+
+## When to Use This Skill
+
+Trigger this skill when:
+- User asks "What cat breed should I get?"
+- User wants help finding a cat that fits their lifestyle
+- User mentions getting a cat and needs guidance
+- User asks about cat breed compatibility
+
+## High-Level Approach
+
+Use the breed-advisor agent which implements a two-phase conversational pattern:
+
+1. **Gathering Phase**: Collect user preferences through natural conversation
+2. **Recommendation Phase**: Present matched breeds
+3. **Refinement Phase**: Answer questions, compare options
+4. **Selection Phase**: Help user make final choice
+
+## Key Factors to Gather
+
+The agent needs these factors (see Factor Definitions for LLM-facing details):
+
+### Critical Factor: Music Preference 🎵
+
+**Why this matters for orchestration:**
+- This is the PRIMARY compatibility factor (novelty hook)
+- Ask about it EARLY in the conversation
+- If user seems confused, explain the music-breed connection
+- See Music Preference Insight for the mapping
+
+**Orchestration tip:** Don't just pass this through - use it as the conversation anchor. The quirky music angle makes the interaction memorable.
+
+### Other Factors
+- Living Space (apartment → large house)
+- Activity Level (couch-companion → high-energy-athlete)
+- Grooming Tolerance (minimal → daily)
+- Family Composition (single → multi-pet household)
+- Allergies (boolean)
+
+## Conversation Orchestration
+
+### Phase 1: Gathering (Natural Dialogue)
+
+**Goal:** Collect ≥4 factors including music preference
+
+**Orchestration strategy:**
+- ONE question at a time (don't bombard user)
+- Start with music (it's unique and engaging)
+- Use natural language (user says "big house" not "large-house")
+- Extract factors after each turn (background process)
+
+**Example flow:**
+```
+Claude: [Welcome Message from agent resources]
+User: "I like jazz"
+Claude: [Acknowledges, asks about living space]
+User: "I have a small apartment"
+Claude: [Acknowledges, asks about activity level]
+...
+```
+
+**When to transition:** ≥4 factors collected AND music preference known
+
+### Phase 2: Recommendations (Structured Presentation)
+
+**Goal:** Present matched breeds, allow exploration
+
+**Orchestration strategy:**
+- Present 3-5 breed recommendations (from matchBreeds algorithm)
+- Format conversationally (not a data dump)
+- Allow user to ask questions about specific breeds
+- User can request more details, compare breeds
+
+**Example interaction:**
+```
+Claude: [Presents 3 breeds with reasoning]
+User: "Tell me more about Maine Coons"
+Claude: [Detailed info about Maine Coons from breed database]
+User: "How do they compare to Persians?"
+Claude: [Comparison highlighting differences]
+```
+
+### Phase 3: Selection (Confirmation)
+
+**Goal:** Detect final choice, conclude gracefully
+
+**Orchestration strategy:**
+- Watch for selection signals ("I'll take", "I want", "sounds good")
+- Extract selection in background
+- Conclude enthusiastically when selection detected
+- Provide exit instruction (`/quit`)
+
+## What Claude Code Does vs What the LLM Does
+
+### Claude Code's Role (This Skill):
+- **Orchestrates** the multi-turn conversation
+- **Monitors** session state (which factors collected)
+- **Triggers** phase transitions (gathering → recommendations → selection)
+- **Manages** context (conversation history, extracted profile)
+- **Calls** the breed-advisor agent at each turn
+
+### LLM's Role (Agent Resources):
+- **Says** the actual prompts (Welcome Message, etc.)
+- **Uses** the domain knowledge (Music Insight)
+- **Follows** the extraction formats (Factor Extraction)
+- **Applies** the conversation strategy (Conversation Strategy)
+
+**Insight:** Skills provide meta-guidance on orchestration. Agents provide actual LLM content.
+
+## Shared vs Separate Content
+
+### What Belongs in Agent Resources (LLM-Facing):
+✅ System prompts and LLM instructions
+✅ Domain knowledge (music-breed mappings, factor definitions)
+✅ Extraction prompts (JSON schemas, format instructions)
+✅ Example conversations (few-shot learning)
+✅ Natural language mappings ("lazy" → "couch-companion")
+
+### What Belongs in Skills (Claude Code-Facing):
+✅ When to use the agent (trigger conditions)
+✅ How to orchestrate multi-turn flow (phase transitions)
+✅ What to monitor (readiness criteria, selection signals)
+✅ Debugging guidance (common issues, pitfalls)
+✅ Meta-strategy (why music first, one question at a time)
+
+### Overlap (Appears in Both):
+⚠️ Conversation flow structure (both need to understand phases)
+⚠️ Factor list (skill explains orchestration, agent explains to LLM)
+⚠️ Readiness criteria (skill monitors, agent implements)
+
+**Resolution:** Keep agent resources authoritative for LLM content. Skills REFERENCE agent resources via links, don't duplicate.
+
+## Example: Music Preference Handling
+
+### In Agent Resources (breed-advisor.md):
+```markdown
+## Music Preference Insight
+CRITICAL: Music preference is the MOST IMPORTANT factor...
+- Classical: Calm, regal breeds (Persian, Ragdoll)
+- Jazz: Intelligent, unpredictable breeds (Siamese, Bengal)
+...
+```
+**Usage:** Injected into LLM system prompt
+
+### In Skills (This File):
+```markdown
+### Critical Factor: Music Preference
+**Why this matters for orchestration:**
+- Primary compatibility factor (novelty hook)
+- Ask EARLY in conversation
+- Use as conversation anchor
+- See [Music Insight](../agents/breed-advisor.md#music-preference-insight) for mapping
+```
+**Usage:** Guides Claude Code on HOW to orchestrate
+
+**Key difference:** Agent says WHAT (the mappings), Skill says WHY and WHEN (orchestration strategy).
+
+## Common Pitfalls
+
+### ❌ Don't: Ask All Questions at Once
+```
+Bad: "Tell me your music taste, living space, activity level, and family composition"
+```
+
+### ✅ Do: One Question at a Time
+```
+Good: "What's your favorite type of music?"
+[User responds]
+Good: "Great! Tell me about your living space..."
+```
+
+### ❌ Don't: Skip Music Preference
+Music is the hook! Don't forget to ask about it.
+
+### ✅ Do: Make Music Central
+Start with music, emphasize its importance, use it as the anchor.
+
+## Debugging: When Things Go Wrong
+
+**User provides unmappable music genre:**
+- Don't silently map hip-hop → rock
+- Ask user: "Hip-hop is great! Which category feels closest: rock, electronic, or pop?"
+- Refer to Factor Definitions for clarification guidance
+
+**User is vague about factors:**
+- Push for specificity (see Conversation Strategy)
+- Don't accept "I'm flexible" for all factors
+- Need at least 4 concrete factors
+
+**Conversation stalls:**
+- Check if enough factors collected (≥4 + music)
+- Transition to recommendations even if not all factors known
+- User can refine later
+
+## Related Agent Resources
+
+- Breed Advisor Agent - Complete agent specification
+  - Welcome Message - First turn greeting
+  - Music Preference Insight - Music-breed mappings
+  - Factor Definitions - All 6 factors explained
+  - Conversation Strategy - LLM guidance
+  - Factor Extraction Prompt - JSON extraction format
+  - Transition Message - Readiness announcement
+  - Recommendation Presentation - How to present breeds
+  - Selection Extraction - Detect final choice
+  - Conclusion Prompt - End conversation
+
+## Success Criteria
+
+Conversation is successful when:
+- User feels heard (not interrogated)
+- Music preference made the conversation memorable
+- At least 4 factors collected
+- Breed recommendations feel personalized
+- User makes a confident selection (or knows they want to research more)
+
+## Additional Resources
+
+Once user selects a breed, you can optionally:
+- Help them name their cat using Name Generator
+- Provide care tips (future skill)
+- Connect with breeders (future skill)

package/dist/skills/vat-example-cat-agents/resources/orchestration-patterns.md

@@ -0,0 +1,168 @@
+# Advanced Orchestration Patterns and CLI Integration
+
+Reference material for [SKILL.md](../SKILL.md). Read this when you need the parallel,
+conditional and checkpointed orchestration shapes, or a worked CLI request/response pair.
+
+## Advanced Orchestration Patterns
+
+### Pattern: Parallel Execution
+
+When agents don't depend on each other, run them in parallel.
+
+**Example:** Generate both name and haiku from same characteristics
+
+```typescript
+const [name, haiku] = await Promise.all([
+  generateCatName(characteristics),
+  generateCatHaiku(characteristics),
+]);
+```
+
+**Benefits:** Faster execution, better user experience
+
+### Pattern: Fallback Chain
+
+When one agent fails, try alternatives.
+
+**Example:** Photo analysis with text description fallback
+
+```typescript
+let characteristics;
+try {
+  characteristics = await analyzePhoto(imagePath);
+} catch {
+  // Fallback to text description
+  const description = await getUserDescription();
+  characteristics = await parseDescription(description);
+}
+```
+
+**Benefits:** Resilience, better error handling
+
+### Pattern: Conditional Routing
+
+Choose agent path based on user input type.
+
+**Example:** Multi-modal input handling
+
+```typescript
+if (input.type === 'image') {
+  characteristics = await analyzePhoto(input.imagePath);
+} else if (input.type === 'text') {
+  characteristics = await parseDescription(input.description);
+} else {
+  // Conversational gathering
+  characteristics = await breedAdvisor.gather();
+}
+```
+
+**Benefits:** Flexible input handling, better UX
+
+### Pattern: Staged Approval
+
+Break complex workflows into approval stages.
+
+**Example:** Multi-stage breeding application
+
+```typescript
+// Stage 1: Basic info approval
+const basicApproval = await humanApproval({ stage: 'basic', data });
+if (!basicApproval.approved) return;
+
+// Stage 2: Detailed questionnaire
+const detailApproval = await humanApproval({ stage: 'detail', data });
+if (!detailApproval.approved) return;
+
+// Stage 3: Final review
+const finalApproval = await humanApproval({ stage: 'final', data });
+```
+
+**Benefits:** Checkpoints prevent wasted work, clearer decision points
+
+## CLI Integration Examples
+
+### Example 1: Validate Name via CLI
+
+```bash
+# Input
+echo '{
+  "name": "Mr. Whiskers",
+  "characteristics": {
+    "physical": {
+      "furColor": "Orange",
+      "furPattern": "Tabby",
+      "size": "medium"
+    },
+    "behavioral": {
+      "personality": ["Playful", "Curious"]
+    }
+  }
+}' | vat agents validate-name
+
+# Output (stdout)
+{
+  "status": "valid",
+  "reason": "Name meets all quirky validation rules",
+  "confidence": 0.95
+}
+---
+# (stderr - empty if no errors)
+```
+
+### Example 2: Validate Haiku via CLI
+
+```bash
+# Input
+echo '{
+  "lines": [
+    "Orange sunset fur",
+    "Paws dance across the tatami",
+    "Zen master purrs"
+  ]
+}' | vat agents validate-haiku
+
+# Output (stdout)
+{
+  "status": "valid",
+  "syllableCounts": [5, 7, 5],
+  "hasKigo": true,
+  "kigo": "sunset",
+  "hasKireji": false,
+  "errors": []
+}
+---
+# (stderr - empty if no errors)
+```
+
+### Example 3: Error Handling
+
+```bash
+# Invalid input
+echo '{"invalid": "schema"}' | vat agents validate-name
+
+# Output
+# (stdout - empty)
+---
+Error: Invalid input schema. Expected 'name' and 'characteristics' fields.
+Schema validation failed:
+  - Missing required field: name
+  - Missing required field: characteristics
+# (exit code: 2)
+```
+
+## Next Steps
+
+Once you've successfully orchestrated agents:
+
+1. **Explore Combinations** - Try chaining agents in new ways
+2. **Add Custom Validation** - Create your own quirky validation rules
+3. **Build New Workflows** - Combine agents for complex use cases
+4. **Contribute Patterns** - Share successful orchestration strategies
+5. **Package Skills** - Create distributable skill packages with pure functions
+
+## Questions?
+
+- **For orchestration patterns:** This file (SKILL.md)
+- **For agent-specific details:** See individual agent resources
+- **For implementation examples:** See examples/ directory
+- **For archetype theory:** See package README.md

package/dist/skills/vat-example-cat-agents/resources/workflow-orchestration.md

@@ -0,0 +1,158 @@
+# Detailed Workflow Orchestration
+
+Reference material for [SKILL.md](../SKILL.md). Read this when you are implementing an
+orchestration end to end rather than choosing between the high-level patterns.
+
+## Detailed Workflow Orchestration
+
+### Workflow A: Breed Selection (Conversational)
+
+**When:** User wants help finding the right cat breed.
+
+**Agent:** breed-advisor
+
+**Orchestration strategy:**
+1. **Phase 1 - Gathering** (see Conversation Strategy)
+   - Collect ≥4 factors including music preference
+   - ONE question at a time (don't bombard)
+   - Extract factors after each turn
+   - Monitor readiness: `factorsCollected >= 4 && musicPreference != null`
+
+2. **Phase 2 - Recommendation**
+   - Present 3-5 matched breeds
+   - Allow exploration, questions, comparisons
+   - Use conversational formatting (not data dump)
+
+3. **Phase 3 - Selection**
+   - Detect selection signals ("I'll take", "sounds good")
+   - Conclude gracefully
+   - Provide next steps or exit instruction
+
+**Critical factor:** Music preference is the PRIMARY compatibility factor. Ask early, use as conversation anchor. See Music Preference Insight for mappings.
+
+**Reference implementation:** See [cat-breed-selection.md](cat-breed-selection.md) for detailed breed selection orchestration.
+
+### Workflow B: Photo Analysis Pipeline
+
+**When:** User provides a cat photo and wants analysis, name, or haiku.
+
+**Agents:** photo-analyzer → name-generator OR haiku-generator
+
+**Orchestration strategy:**
+
+```
+Step 1: Analyze Photo
+- Input: Image path/URL
+- Agent: photo-analyzer
+- Output: CatCharacteristics
+- Note: Supports mock mode (reads EXIF) for testing
+
+Step 2: Generate Content
+- Input: CatCharacteristics from Step 1
+- Agent: name-generator OR haiku-generator
+- Output: NameSuggestion OR Haiku
+
+Optional Step 3: Validate
+- Input: Generated content + original characteristics
+- Agent: name-validator OR haiku-validator (pure functions)
+- Output: Validation result
+- If invalid: Retry Step 2 with feedback
+```
+
+**Mockable behavior:** photo-analyzer reads EXIF metadata in mock mode. For production, set `mockable: false` to use real vision API.
+
+### Workflow C: Text Description Pipeline
+
+**When:** User describes a cat in text (no photo).
+
+**Agents:** description-parser → name-generator OR haiku-generator
+
+**Orchestration strategy:**
+
+```
+Step 1: Parse Description
+- Input: Text description
+- Agent: description-parser
+- Output: CatCharacteristics (same schema as photo-analyzer!)
+
+Step 2-3: Same as Workflow B
+- Multi-modal convergence: photo and text produce same schema
+- Downstream agents (name-gen, haiku-gen) work with either
+```
+
+**Key insight:** Photo and text paths converge at `CatCharacteristics` schema. This enables multi-modal workflows without agent changes.
+
+### Workflow D: Generate-Validate-Retry Loop
+
+**When:** Generator produces content that must pass validation rules.
+
+**Pattern:** Generator (LLM) + Validator (pure function) + Retry logic
+
+**Implementation:**
+
+```typescript
+// Pseudo-code for orchestration
+let attempts = 0;
+const maxAttempts = 3;
+
+while (attempts < maxAttempts) {
+  // Generate content
+  const suggestion = await generator(characteristics);
+
+  // Validate (pure function, instant)
+  const validation = validator(suggestion, characteristics);
+
+  if (validation.status === 'valid') {
+    return suggestion; // Success!
+  }
+
+  // Retry with feedback
+  attempts++;
+  // Optional: Adjust approach based on validation.reason
+}
+
+throw new Error('Could not generate valid content after 3 attempts');
+```
+
+**Why this pattern works:**
+- Generator has NO knowledge of validation rules (isolated concerns)
+- Validator is deterministic (pure function, fast)
+- Feedback loop tests multi-turn orchestration
+- ~60-70% initial rejection rate forces iteration
+
+**Agents using this pattern:**
+- name-generator + name-validator
+- haiku-generator + haiku-validator
+
+### Workflow E: HITL Approval Gate
+
+**When:** Decision requires human judgment (compliance, taste, ethics).
+
+**Agent:** human-approval
+
+**Orchestration strategy:**
+
+```
+Step 1: Prepare Request
+- Gather all necessary context
+- Format clearly for human reviewer
+- Include relevant data (characteristics, generated content, reasoning)
+
+Step 2: Emit Approval Request
+- Agent: human-approval
+- Input: Request payload
+- Behavior: Blocks waiting for response
+- Timeout: Configurable (default: 60s)
+
+Step 3: Handle Response
+- Approved: Continue workflow
+- Rejected: Handle gracefully (retry, inform user, etc.)
+- Timeout: Fall back to safe default or escalate
+```
+
+**Mockable behavior:** Set `mockable: true` to auto-approve without human (useful for testing).
+
+**Real-world uses:**
+- Breeding application approval
+- Name selection from alternatives
+- Content moderation decisions