refactor(create-expert): make ecosystem-builder instruction declarative

.changeset/declarative-ecosystem-builder.md

@@ -0,0 +1,13 @@
+---
+"create-expert": patch
+---
+
+Refactor ecosystem-builder instruction to be declarative
+
+Per best practices, replaced procedural "Step 1/2" language with
+declarative policies and domain knowledge:
+
+- Removed "Step 1: Analyze Dependencies" / "Step 2: Generate Ecosystem"
+- Simplified Setup Expert template (removed numbered phases)
+- Simplified Doctor Expert template (removed numbered diagnostic steps)
+- Focus on what to achieve, not how to achieve it

apps/create-expert/src/lib/create-expert-toml.ts

@@ -92,23 +92,15 @@ First read the file to understand the existing structure, then append your Exper
 Do NOT use writeTextFile - it would overwrite the entire file.
 Do NOT modify model, runtime, or provider settings - they already exist.
 
-## Ecosystem Generation Strategy
+## Ecosystem Structure
 
-### Step 1: Analyze Dependencies
-From the properties, identify:
-- Required API keys (e.g., BRAVE_API_KEY, OPENAI_API_KEY)
-- External services or tools
-- Environment variables needed
+Every ecosystem includes:
+- **Main Expert**: Core functionality
+- **Demo Expert**: Works without configuration, uses embedded sample data
 
-### Step 2: Generate Ecosystem
-
-**ALWAYS generate:**
-- Main expert (core functionality)
-- Demo expert (with sample/mock data)
-
-**IF external dependencies exist, ALSO generate:**
-- Setup expert (automated configuration wizard)
-- Doctor expert (troubleshooting assistant)
+When external dependencies exist (API keys, services, environment variables):
+- **Setup Expert**: Guides users through configuration
+- **Doctor Expert**: Diagnoses configuration issues
 
 ## Expert Templates
 
@@ -173,27 +165,15 @@ You guide users through setting up <name>.
 ## Your Role
 Help users configure required dependencies quickly and correctly.
 
-## Setup Process
-
-### 1. Check Current Configuration
-- Check if .env file exists
-- Check if required environment variables are set
-- Report current status
-
-### 2. Guide Through Missing Configuration
-For each missing dependency:
-- Explain what it is and why it's needed
-- Provide URL to obtain it (e.g., API key signup page)
-- Ask user for the value
-- Validate the format
-- Save to .env file
+## Configuration Policies
+- Check .env file and environment variables 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
 
-### 3. Verify Configuration
-- Run a simple test to verify the configuration works
-- If test fails, explain what went wrong and how to fix it
-
-### 4. Confirm Success
-Output: "✓ Setup complete! Try: npx perstack run <name> \\"your query\\""
+## Success Output
+"✓ Setup complete! Try: npx perstack run <name> \\"your query\\""
 
 ## Required Dependencies
 [List the specific dependencies this expert needs]
@@ -217,33 +197,14 @@ You diagnose and help fix issues with <name>.
 ## Your Role
 Run diagnostics and provide actionable fixes for common problems.
 
-## Diagnostic Checks
-
-### 1. Environment Check
-- Verify required environment variables exist
-- Check .env file for proper formatting
-- Validate API key formats
-
-### 2. Connectivity Check
-- Test network connectivity to required services
-- Verify API endpoints are reachable
-
-### 3. Configuration Validation
-- Run a simple test query
-- Analyze any error messages
+## Diagnostic Areas
+- Environment: Verify variables exist and are properly formatted
+- Connectivity: Test network access to required services
+- Configuration: Run test query and analyze errors
 
 ## Output Format
-For each issue found:
-\`\`\`
-❌ Issue: [What's wrong]
-   Why it matters: [Impact]
-   To fix: [Exact steps to resolve]
-\`\`\`
-
-If no issues found:
-\`\`\`
-✓ All checks passed! <name> is ready to use.
-\`\`\`
+For issues: "❌ Issue: [problem] | To fix: [steps]"
+If healthy: "✓ All checks passed! <name> is ready to use."
 '''
 
 [experts."<name>-doctor".skills."@perstack/base"]