From d7109eaed87fa9c56409adcea7cf1d52352309fc Mon Sep 17 00:00:00 2001 From: HiranoMasaaki Date: Sat, 3 Jan 2026 05:37:37 +0000 Subject: [PATCH] refactor(create-expert): make ecosystem-builder instruction declarative MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Replace procedural language with declarative policies: - Remove "Step 1/2" sections, replace with "Ecosystem Structure" - Simplify Setup Expert template: replace 4 numbered phases with policies - Simplify Doctor Expert template: replace 3 numbered checks with areas Per docs/making-experts/best-practices.md: > The LLM knows how to have a conversation. What it doesn't know > is your company's policies — that's domain knowledge. Closes #353 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- .changeset/declarative-ecosystem-builder.md | 13 +++ .../src/lib/create-expert-toml.ts | 81 +++++-------------- 2 files changed, 34 insertions(+), 60 deletions(-) create mode 100644 .changeset/declarative-ecosystem-builder.md diff --git a/.changeset/declarative-ecosystem-builder.md b/.changeset/declarative-ecosystem-builder.md new file mode 100644 index 00000000..c84d1679 --- /dev/null +++ b/.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 diff --git a/apps/create-expert/src/lib/create-expert-toml.ts b/apps/create-expert/src/lib/create-expert-toml.ts index c355d11a..d95336da 100644 --- a/apps/create-expert/src/lib/create-expert-toml.ts +++ b/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 . ## 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 \\"your query\\"" +## Success Output +"✓ Setup complete! Try: npx perstack run \\"your query\\"" ## Required Dependencies [List the specific dependencies this expert needs] @@ -217,33 +197,14 @@ You diagnose and help fix issues with . ## 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! is ready to use. -\`\`\` +For issues: "❌ Issue: [problem] | To fix: [steps]" +If healthy: "✓ All checks passed! is ready to use." ''' [experts."-doctor".skills."@perstack/base"]