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

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

package/package.json

@@ -1,6 +1,6 @@
 {
   "name": "@vibe-agent-toolkit/vat-example-cat-agents",
-  "version": "0.2.0-rc.5",
+  "version": "0.2.0-rc.7",
   "description": "Example agents: 8 quirky cat agents demonstrating VAT patterns",
   "type": "module",
   "exports": {
@@ -36,9 +36,9 @@
     "postinstall": "vat skills install --npm-postinstall || exit 0"
   },
   "dependencies": {
-    "@vibe-agent-toolkit/agent-runtime": "0.2.0-rc.5",
-    "@vibe-agent-toolkit/schema": "0.2.0-rc.5",
-    "@vibe-agent-toolkit/transports": "0.2.0-rc.5",
+    "@vibe-agent-toolkit/agent-runtime": "0.2.0-rc.7",
+    "@vibe-agent-toolkit/schema": "0.2.0-rc.7",
+    "@vibe-agent-toolkit/transports": "0.2.0-rc.7",
     "syllable": "^5.0.1",
     "zod": "^3.24.1"
   },
@@ -47,15 +47,15 @@
     "@anthropic-ai/sdk": "^0.36.0",
     "@langchain/openai": "^1.5.11",
     "@types/node": "^22.10.5",
-    "@vibe-agent-toolkit/resource-compiler": "0.2.0-rc.5",
-    "@vibe-agent-toolkit/runtime-claude-agent-sdk": "0.2.0-rc.5",
-    "@vibe-agent-toolkit/runtime-langchain": "0.2.0-rc.5",
-    "@vibe-agent-toolkit/runtime-openai": "0.2.0-rc.5",
-    "@vitest/coverage-v8": "^3.2.4",
+    "@vibe-agent-toolkit/resource-compiler": "0.2.0-rc.7",
+    "@vibe-agent-toolkit/runtime-claude-agent-sdk": "0.2.0-rc.7",
+    "@vibe-agent-toolkit/runtime-langchain": "0.2.0-rc.7",
+    "@vibe-agent-toolkit/runtime-openai": "0.2.0-rc.7",
+    "@vitest/coverage-v8": "^4.1.11",
     "ai": "^6.0.48",
     "openai": "^4.77.3",
     "typescript": "^5.7.3",
-    "vitest": "^3.2.4"
+    "vitest": "^4.1.11"
   },
   "vat": {
     "version": "1.0",
@@ -77,7 +77,7 @@
   "author": "Jeff Dutton",
   "license": "MIT",
   "engines": {
-    "node": ">=22.0.0"
+    "node": ">=22.13.0"
   },
   "repository": {
     "type": "git",