From 682798e5ad005d0f131797393604f2908909bd41 Mon Sep 17 00:00:00 2001 From: HiranoMasaaki Date: Sat, 3 Jan 2026 07:31:57 +0000 Subject: [PATCH 1/2] refactor(create-expert): reduce template redundancy in ecosystem-builder MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Extract common error format to single definition and simplify templates. Changes: - Add "Error Format (all ecosystem experts)" section with standard format - Remove duplicate error handling sections from each template - Simplify template instructions (remove redundant explanations) - Reference "standard error format" instead of repeating it - Remove "Setup expert should complete in < 2 minutes" (time-based, untestable) Before: Each template had its own error handling section with slight variations After: Single error format definition, templates reference it Closes #381 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- .../src/lib/create-expert-toml.ts | 74 +++++++------------ 1 file changed, 25 insertions(+), 49 deletions(-) diff --git a/apps/create-expert/src/lib/create-expert-toml.ts b/apps/create-expert/src/lib/create-expert-toml.ts index d77fc651..3068a86e 100644 --- a/apps/create-expert/src/lib/create-expert-toml.ts +++ b/apps/create-expert/src/lib/create-expert-toml.ts @@ -119,6 +119,16 @@ When external dependencies exist (API keys, services, environment variables): - **Setup Expert**: Guides users through configuration - **Doctor Expert**: Diagnoses configuration issues +## Error Format (all ecosystem experts) + +All errors must follow this format: +\`\`\` +❌ [Type]: [description] | To fix: [actionable steps] +\`\`\` + +Where [Type] is: Error, Failed, or Issue depending on context. +Never fail silently - always explain what happened and how to resolve it. + ## Expert Templates ### Main Expert Template @@ -129,10 +139,7 @@ description = "Brief description of main functionality" instruction = ''' Your role and capabilities... -## Error Handling -When errors occur, provide actionable guidance: -- "❌ Error: [what went wrong] | To fix: [specific steps]" -- Never fail silently - always explain what happened and how to resolve it +[Include domain knowledge, policies, and expected behavior] ''' [experts."".skills."@perstack/base"] @@ -150,33 +157,13 @@ description = "Interactive demo with sample data - no setup required" instruction = ''' You demonstrate the capabilities of using built-in sample data. -## Your Role -Show users what the expert can do WITHOUT requiring any setup or API keys. - ## Demo Mode -- Use the embedded sample data below (do NOT make API calls) -- Demonstrate key features with realistic examples +- Use embedded sample data (do NOT make API calls) - Show expected output format -- Explain what would happen with real configuration +- Explain what real configuration would enable ## Embedded Sample Data -IMPORTANT: Include actual sample data here, not placeholders. -Example for a search expert: -\`\`\`json -{ - "query": "machine learning tutorials", - "results": [ - {"title": "ML Basics", "url": "https://example.com/ml", "snippet": "Learn the fundamentals..."}, - {"title": "Deep Learning Guide", "url": "https://example.com/dl", "snippet": "Advanced neural networks..."} - ] -} -\`\`\` - -## Output -Provide a realistic demonstration that helps users understand: -1. What this expert does -2. What kind of input it expects -3. What output they will get +[Include actual sample data - not placeholders] ''' [experts."-demo".skills."@perstack/base"] @@ -194,26 +181,19 @@ description = "Automated setup wizard for " instruction = ''' You guide users through setting up . -## Your Role -Help users configure required dependencies quickly and correctly. - ## Configuration Policies -- Check .env file and environment variables first +- Check .env file and environment first - For missing items: explain purpose, provide signup URL, validate format -- Save configuration to .env file -- Verify with a simple test before confirming success -- Target: Complete setup in under 2 minutes +- Save to .env file and verify before confirming ## Success Output "✓ Setup complete! Try: npx perstack run \\"your query\\"" -## Error Handling -When setup fails, guide the user: -- "❌ Failed: [what went wrong] | To fix: [specific steps]" -- Suggest running the doctor expert for diagnostics +## On Failure +Suggest running -doctor for diagnostics. ## Required Dependencies -[List the specific dependencies this expert needs] +[List specific dependencies] ''' [experts."-setup".skills."@perstack/base"] @@ -231,16 +211,13 @@ description = "Diagnose and fix issues with " instruction = ''' You diagnose and help fix issues with . -## Your Role -Run diagnostics and provide actionable fixes for common problems. - ## Diagnostic Areas -- Environment: Verify variables exist and are properly formatted -- Connectivity: Test network access to required services -- Configuration: Run test query and analyze errors +- Environment: Verify variables exist and format +- Connectivity: Test network access +- Configuration: Run test query and analyze -## Output Format -For issues: "❌ Issue: [problem] | To fix: [steps]" +## Output +For issues: Use standard error format If healthy: "✓ All checks passed! is ready to use." ''' @@ -257,8 +234,7 @@ pick = ["readTextFile", "exec", "attemptCompletion"] 3. Use @perstack/base for file/shell operations 4. ALWAYS use pick for minimal privilege 5. Demo expert must work WITHOUT any setup -6. Setup expert should complete in < 2 minutes -7. All errors must include "To fix: ..." guidance +6. All errors must follow the standard error format above ` const FUNCTIONAL_MANAGER_INSTRUCTION = `You verify functional quality through three test categories. From 47e421164012c55d1aeaf81ec41eb5dbcc73c1b9 Mon Sep 17 00:00:00 2001 From: HiranoMasaaki Date: Sat, 3 Jan 2026 07:39:59 +0000 Subject: [PATCH 2/2] chore: add changeset for #381 --- .changeset/refactor-381-template-redundancy.md | 6 ++++++ 1 file changed, 6 insertions(+) create mode 100644 .changeset/refactor-381-template-redundancy.md diff --git a/.changeset/refactor-381-template-redundancy.md b/.changeset/refactor-381-template-redundancy.md new file mode 100644 index 00000000..8d95cb2a --- /dev/null +++ b/.changeset/refactor-381-template-redundancy.md @@ -0,0 +1,6 @@ +--- +"create-expert": patch +--- + +Reduce template redundancy in ecosystem-builder +