diff --git a/.changeset/schema-example-best-practices.md b/.changeset/schema-example-best-practices.md new file mode 100644 index 00000000..0b84077d --- /dev/null +++ b/.changeset/schema-example-best-practices.md @@ -0,0 +1,6 @@ +--- +"perstack": patch +"@perstack/runtime": patch +--- + +feat: add Example/Best Practices to schema, recommend plan→execute→verify pattern, relax subdivision guidance diff --git a/definitions/create-expert/perstack.toml b/definitions/create-expert/perstack.toml index 2fe55e7d..e79bf65c 100644 --- a/definitions/create-expert/perstack.toml +++ b/definitions/create-expert/perstack.toml @@ -38,7 +38,7 @@ [experts."create-expert"] defaultModelTier = "high" -version = "2.0.0" +version = "2.0.1" description = "Creates and modifies Perstack expert definitions in perstack.toml" instruction = """ You create and modify Perstack expert definitions. perstack.toml is the single deliverable. @@ -86,7 +86,7 @@ pick = ["readTextFile", "exec", "attemptCompletion"] [experts."@create-expert/plan"] defaultModelTier = "high" -version = "2.0.0" +version = "2.0.1" description = """ Expands the user's request into a comprehensive plan.md through information gathering and prior knowledge. Provide: (1) the user's request, (2) optionally path to existing perstack.toml. @@ -111,6 +111,12 @@ Constraints and rules the LLM cannot derive on its own, extracted from the user' ### Expert Architecture Delegation tree with role assignments. If the user specified a team name, use it exactly as the coordinator name. Delegate names describe function, not persona (/test, /verify, not /tester). For each expert: name, one-line purpose, role only. +Recommended pattern: **plan → execute → verify** +- A /plan expert expands context (requirements, domain knowledge, constraints) before work begins +- An execution expert (or a few, if roles are genuinely distinct) does the actual work +- A /verify expert checks the result with a hard signal (command + expected output) +A single execution expert is fine when the role is straightforward. Only split execution into multiple experts when responsibilities are genuinely distinct — unnecessary subdivision adds latency and coordination overhead without improving quality. + ### Test Query One comprehensive, realistic query that exercises the expert's full capability. @@ -148,7 +154,7 @@ pick = [ [experts."@create-expert/write"] defaultModelTier = "high" -version = "2.0.0" +version = "2.0.1" description = """ Produces perstack.toml from plan.md using CLI validation tools. Provide: (1) path to plan.md, (2) optionally path to existing perstack.toml, (3) optionally verification failure feedback. @@ -217,7 +223,7 @@ pick = [ [experts."@create-expert/verify"] defaultModelTier = "high" -version = "2.0.0" +version = "2.0.1" description = """ Runs the expert with a test query and checks the ONE completion signal. Provide: (1) path to perstack.toml, (2) path to plan.md, (3) the coordinator expert name. diff --git a/packages/perstack-toml/src/schema-printer.ts b/packages/perstack-toml/src/schema-printer.ts index 06a31b08..58d37352 100644 --- a/packages/perstack-toml/src/schema-printer.ts +++ b/packages/perstack-toml/src/schema-printer.ts @@ -127,5 +127,66 @@ export function printPerstackSchema(): string { sections.push("- Delegates cannot delegate to their own coordinator") sections.push("") + sections.push("## Example") + sections.push("") + sections.push("```toml") + sections.push('[experts."my-team"]') + sections.push('version = "1.0.0"') + sections.push('defaultModelTier = "high"') + sections.push('description = "Coordinates task execution and delegates to specialists"') + sections.push('instruction = """') + sections.push("Domain-specific constraints and coordination rules here.") + sections.push('"""') + sections.push('delegates = ["@my-team/build", "@my-team/verify"]') + sections.push("") + sections.push('[experts."my-team".skills."@perstack/base"]') + sections.push('type = "mcpStdioSkill"') + sections.push('command = "npx"') + sections.push('packageName = "@perstack/base"') + sections.push('pick = ["readTextFile", "exec", "attemptCompletion"]') + sections.push("") + sections.push('[experts."@my-team/build"]') + sections.push('version = "1.0.0"') + sections.push('defaultModelTier = "middle"') + sections.push('description = "Implements the core deliverable"') + sections.push('instruction = """') + sections.push("Domain constraints for this specialist.") + sections.push('"""') + sections.push("") + sections.push('[experts."@my-team/build".skills."@perstack/base"]') + sections.push('type = "mcpStdioSkill"') + sections.push('command = "npx"') + sections.push('packageName = "@perstack/base"') + sections.push( + 'pick = ["readTextFile", "writeTextFile", "editTextFile", "exec", "todo", "attemptCompletion"]', + ) + sections.push("```") + sections.push("") + + sections.push("## Best Practices") + sections.push("") + sections.push("- Always set version, defaultModelTier, and description on every expert") + sections.push("- Always set an explicit pick list — omitting it grants ALL tools") + sections.push( + "- Instructions should contain only domain constraints the LLM cannot derive on its own", + ) + sections.push( + "- Do not put implementation procedures, file paths, or data schemas in instructions", + ) + sections.push("- Shorter instructions outperform longer ones — every line must earn its place") + sections.push( + "- Delegate names should describe function, not persona (/build, /verify, not /builder)", + ) + sections.push( + "- Coordinators should have minimal pick lists (readTextFile, exec, attemptCompletion)", + ) + sections.push( + "- Leaf experts doing file I/O need: readTextFile, writeTextFile, editTextFile, exec, todo, attemptCompletion", + ) + sections.push( + "- Experts managing delegation need: addDelegateFromConfig, addDelegate, removeDelegate", + ) + sections.push("") + return sections.join("\n") } diff --git a/packages/runtime/src/messages/instruction-message.ts b/packages/runtime/src/messages/instruction-message.ts index 8e3c14c6..e8ed1c38 100644 --- a/packages/runtime/src/messages/instruction-message.ts +++ b/packages/runtime/src/messages/instruction-message.ts @@ -44,8 +44,8 @@ function getCoordinatorMetaInstruction(): string { 6. Aggregate results and clean up the workspace. Delegation guidelines: - - Be specific: include context, file paths, constraints, and expected output format. No vague delegations. - - Break large subtasks into focused units rather than overloading a single delegate. + - Be specific: include context, constraints, and expected output format. No vague delegations. + - A single delegate can handle a broad task if the role is straightforward. Only split into multiple delegates when responsibilities are genuinely distinct — unnecessary subdivision adds overhead without improving quality. - If no suitable delegate exists, use createExpert to create one, then addDelegate to register it. Workspace cleanup: