feat(create-expert): Generate Expert Ecosystems with Usability Focus

[FL4TLiN3]

Summary

Transform create-expert from generating single experts to generating expert ecosystems with built-in usability:

• Main expert: Core functionality
• Demo expert (<name>-demo): Works immediately with sample data (no setup required)
• Setup expert (<name>-setup): Automated configuration wizard (only if external deps exist)
• Doctor expert (<name>-doctor): Troubleshooting assistant (only if external deps exist)

Changes

1. property-extractor: Added usability properties (Zero-Config, Setup-Automation, Error-Guidance) and external dependencies analysis
2. ecosystem-builder: Replaced expert-builder with ecosystem generation (includes templates for demo, setup, doctor experts)
3. usability-manager: New PDCA manager for usability testing
4. expert-tester: Added usability stage handling
5. report-generator: Updated to show ecosystem info and quick start guide

Expected Behavior

After this change, when a user creates an expert with external dependencies:

npx create-expert --headless --description "A web researcher using Brave Search"

They get an ecosystem:

web-researcher       # Main expert
web-researcher-demo  # Try without setup
web-researcher-setup # Automated API key configuration
web-researcher-doctor # Troubleshooting

Test Plan

• Verify create-expert generates ecosystem for experts with external dependencies
• Verify demo expert works without any setup
• Verify setup expert guides through configuration
• Verify doctor expert diagnoses issues
• Verify usability-manager tests all ecosystem experts

Closes #337

🤖 Generated with Claude Code

---

Note

Transforms create-expert to produce an expert ecosystem instead of a single expert.

• Ecosystem generation: Replaces expert-builder with ecosystem-builder; adds templates for main, -demo, -setup, -doctor; append-only edits to perstack.toml
• Usability focus: property-extractor now returns usability properties (Zero-Config, Setup-Automation, Error-Guidance) and external dependencies
• New PDCA stage: Adds usability-manager; updates expert-tester with a "usability" stage to validate demo w/o setup, guided setup, doctor diagnostics, and actionable error guidance
• Reporting: report-generator updated for ecosystem-aware outputs and quick start commands
• Orchestration: Updates create-expert delegates to include ecosystem-builder and usability-manager; adds/renames expert definitions in TOML

^{Written by Cursor Bugbot for commit 8487774. This will update automatically on new commits. Configure here.}

[codecov]

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

[cursor]

Usability manager may incorrectly create doctor expert

The USABILITY_MANAGER_INSTRUCTION's Act phase says "If doctor missing: Generate doctor expert" without any conditional check. However, ECOSYSTEM_BUILDER_INSTRUCTION explicitly states doctor experts are only created "IF external dependencies exist". This inconsistency means usability-manager could create a doctor expert even when there are no external dependencies, contradicting the ecosystem design where doctor experts are only meant for experts with external API keys or services.

Additional Locations (1)

• apps/create-expert/src/lib/create-expert-toml.ts#L119-L122

 

[cursor]

Incorrect escaping produces visible backslashes in output template

The escaped double quotes \\"your query\\" in the Setup Expert Template instruction are unnecessary in JavaScript template literals. This produces the literal characters \"your query\" with visible backslashes in the final TOML instruction. When the generated setup expert displays the success message, it would show something like npx perstack run name \"your query\" with visible backslash characters instead of clean quotes, which looks incorrect to end users.