Skip to content

Refactor: ecosystem-builder instruction is too procedural #353

@FL4TLiN3

Description

@FL4TLiN3

Description

The ecosystem-builder expert's instruction in create-expert-toml.ts uses a heavily procedural style with numbered steps, which contradicts the best practice documented in docs/making-experts/best-practices.md:

Pitfall: Step-by-step instructions that become unmaintainable.
The LLM knows how to have a conversation. What it doesn't know is your company's policies — that's domain knowledge.

Current State

The ECOSYSTEM_BUILDER_INSTRUCTION (lines 75-267) contains:

## Ecosystem Generation Strategy

### 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

### 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)

This is procedural ("Step 1", "Step 2") rather than declarative.

Target State

Focus on domain knowledge and policies rather than procedures:

## Your Role
Generate Expert ecosystems that are immediately usable.

## Ecosystem Structure
Every ecosystem includes:
- Main expert: Core functionality
- Demo expert: Works without configuration, uses sample data

When external dependencies exist (API keys, services), also include:
- Setup expert: Guides users through configuration
- Doctor expert: Diagnoses configuration issues

## Design Policies
- Always use pick for minimal privilege
- Demo must work without any environment variables
- Setup should complete in under 2 minutes
- All errors include "To fix: ..." guidance

Affected Areas

  • apps/create-expert/src/lib/create-expert-toml.ts:75-267 (ECOSYSTEM_BUILDER_INSTRUCTION)

Acceptance Criteria

  • Remove "Step 1", "Step 2" procedural language
  • Focus on domain knowledge (what an ecosystem should contain)
  • Focus on policies (design principles, constraints)
  • Trust the LLM to figure out the "how"

Metadata

Metadata

Assignees

No one assigned

    Labels

    create-expertcreate-expert CLI packagerefactorCode improvement without behavior change

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions