feat: add Example and Best Practices to perstack schema output

.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

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.

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")
 }

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: