Skip to content

fix(create-expert): improve description clarity for internal experts #367

New issue

Have a question about this project? Sign up for a free GitHub account to open an issue and contact its maintainers and the community.

Sign up for GitHub

By clicking “Sign up for GitHub”, you agree to our terms of service and privacy statement. We’ll occasionally send you account related emails.

Already on GitHub? Sign in to your account

Merged
FL4TLiN3 merged 1 commit into from
Jan 3, 2026
Merged

fix(create-expert): improve description clarity for internal experts #367

Show file tree
Hide file tree
Changes from all commits
Commits
Show all changes
1 commit
Select commit
File filter

Filter by extension

Filter by extension
Conversations
Failed to load comments.
Loading
Jump to
Jump to file
Failed to load files.
Loading
Diff view
Diff view
14 changes: 14 additions & 0 deletions .changeset/improve-descriptions.md
View file
Open in desktop
Original file line number Diff line number Diff line change
@@ -0,0 +1,14 @@
---
"create-expert": patch
---

Improve description clarity for internal PBT framework experts

Each description now includes:
- What the expert does
- What input to provide
- What output to expect

This follows the documentation guidance: "A good description tells
potential callers what this Expert can do, when to use it, and what
to include in the query."
12 changes: 6 additions & 6 deletions apps/create-expert/src/lib/create-expert-toml.ts
View file
Open in desktop
Original file line number Diff line number Diff line change
Expand Up @@ -623,7 +623,7 @@ pick = ["attemptCompletion"]

[experts."property-extractor"]
version = "1.0.0"
description = "Extracts testable properties from user requirements"
description = "Extracts testable properties from user requirements. Provide requirements text. Returns user properties, Perstack properties, usability properties, and external dependencies."
instruction = '''
${PROPERTY_EXTRACTOR_INSTRUCTION}
'''
Expand All @@ -638,7 +638,7 @@ pick = ["attemptCompletion"]

[experts."ecosystem-builder"]
version = "1.0.0"
description = "Creates Expert ecosystem (main + demo + setup + doctor)"
description = "Creates Expert ecosystem from properties. Provide extracted properties and requirements. Returns perstack.toml with main, demo, and optionally setup/doctor experts."
instruction = '''
${ECOSYSTEM_BUILDER_INSTRUCTION}
'''
Expand All @@ -653,7 +653,7 @@ pick = ["readTextFile", "appendTextFile", "attemptCompletion"]

[experts."integration-manager"]
version = "1.0.0"
description = "Orchestrates coordinated functional and usability testing"
description = "Orchestrates functional and usability testing in parallel. Provide ecosystem info and properties. Returns integration report with scores and recommendations."
instruction = '''
${INTEGRATION_MANAGER_INSTRUCTION}
'''
Expand All @@ -669,7 +669,7 @@ pick = ["attemptCompletion"]

[experts."functional-manager"]
version = "1.0.0"
description = "Manages all functional PDCA cycles (happy-path, unhappy-path, adversarial)"
description = "Runs happy-path, unhappy-path, and adversarial tests. Provide properties and ecosystem. Returns functional test report with pass/fail counts."
instruction = '''
${FUNCTIONAL_MANAGER_INSTRUCTION}
'''
Expand All @@ -685,7 +685,7 @@ pick = ["attemptCompletion"]

[experts."usability-manager"]
version = "1.0.0"
description = "Manages usability PDCA cycle for expert ecosystem"
description = "Tests usability of expert ecosystem (demo, setup, doctor, errors). Provide ecosystem and properties. Returns usability report."
instruction = '''
${USABILITY_MANAGER_INSTRUCTION}
'''
Expand All @@ -701,7 +701,7 @@ pick = ["attemptCompletion"]

[experts."expert-tester"]
version = "1.0.0"
description = "Executes tests and reports property-wise results"
description = "Executes tests against experts. Provide stage, expert name, properties, and test cases. Returns property-wise pass/fail results."
instruction = '''
${EXPERT_TESTER_INSTRUCTION}
'''
Expand Down