@vibe-agent-toolkit/vat-example-cat-agents 0.2.0-rc.5 → 0.2.0-rc.7

package/dist/skills/vat-example-cat-agents/SKILL.md

@@ -95,157 +95,8 @@ Use when decision requires human judgment.
 
 ## 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 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
+Step-by-step orchestration for each archetype — inputs, hand-offs and failure handling — is in
+[workflow-orchestration.md](resources/workflow-orchestration.md).
 
 ## CLI Exposure for Pure Functions
 
@@ -526,9 +377,7 @@ Good: "What's your favorite type of music?" → [response] → "Great! Tell me a
 - Human Approval - HITL approval gate
 
 ### Related Documentation
-- Cat Breed Selection Skill - Detailed breed advisor orchestration
-- Package README - Human-facing documentation
-- Package Structure - Technical organization
+- [Cat Breed Selection Skill](resources/cat-breed-selection.md) - Detailed breed advisor orchestration
 
 ## Success Criteria
 
@@ -565,166 +414,7 @@ Your orchestration is successful when:
 - Approval/rejection handled appropriately
 - User understands what happened
 
-## 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?
+## Advanced Patterns and CLI Integration
 
-- **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
+Parallel, conditional and checkpointed orchestration, plus worked CLI request/response pairs,
+are in [orchestration-patterns.md](resources/orchestration-patterns.md).

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)