fix: complete write schema reference and add structural checks to review

definitions/create-expert/perstack.toml

@@ -41,7 +41,7 @@
 
 [experts."create-expert"]
 defaultModelTier = "high"
-version = "1.0.24"
+version = "1.0.25"
 description = "Creates and modifies Perstack expert definitions in perstack.toml"
 instruction = """
 You create and modify Perstack expert definitions. perstack.toml is the single deliverable.
@@ -89,7 +89,7 @@ pick = ["readTextFile", "exec", "attemptCompletion"]
 
 [experts."@create-expert/write"]
 defaultModelTier = "high"
-version = "1.0.24"
+version = "1.0.25"
 description = """
 Produces perstack.toml from the user's request. The file includes an embedded test spec in the header comments.
 Provide: (1) the user's request, (2) optionally path to existing perstack.toml, (3) optionally verification failure feedback.
@@ -146,6 +146,7 @@ Every hard signal is: run X → expect Y. No soft language ("verify that", "look
 ```toml
 [experts."expert-name"]
 version = "1.0.0"
+defaultModelTier = "middle"          # REQUIRED: "low" | "middle" | "high"
 description = "What it does, when to use, what to provide"
 instruction = \"\"\"Domain constraints only.\"\"\"
 delegates = ["@expert-name/delegate"]  # REQUIRED for coordinators
@@ -154,14 +155,23 @@ delegates = ["@expert-name/delegate"]  # REQUIRED for coordinators
 type = "mcpStdioSkill"
 command = "npx"
 packageName = "@perstack/base"
-pick = ["tool1", "tool2"]
-
-[experts."@expert-name/delegate"]
-version = "1.0.0"
-description = "What it does"
-instruction = \"\"\"Domain constraints only.\"\"\"
+pick = ["readTextFile", "exec", "attemptCompletion"]
 ```
 
+Allowed fields per expert: version, defaultModelTier, description, instruction, delegates (coordinators only). Do NOT add fields not shown above (no `instructionFile`, no `defaultSkill`, no custom fields).
+
+Valid defaultModelTier values: `"low"`, `"middle"`, `"high"`. No abbreviations.
+
+Valid tool names for pick: `readTextFile`, `writeTextFile`, `editTextFile`, `exec`, `todo`, `attemptCompletion`, `addDelegateFromConfig`, `addDelegate`, `removeDelegate`. No other names are valid.
+
+## Instruction Quality
+
+Instructions should contain ONLY what the LLM cannot derive on its own: domain-specific constraints, quality bars, anti-patterns, completion criteria, priority rules.
+
+Do NOT put in instructions: implementation procedures, specific command flags, exit code specifications, file paths, data schemas, or step-by-step build instructions. The LLM knows how to implement — tell it what constraints to satisfy, not how to work.
+
+Shorter instructions outperform longer ones. Every line must earn its place.
+
 ## Writing Rules
 
 - Coordinators = kebab-case, delegates = `@coordinator/delegate-name`
@@ -205,7 +215,7 @@ pick = [
 
 [experts."@create-expert/review"]
 defaultModelTier = "low"
-version = "1.0.24"
+version = "1.0.25"
 description = """
 Reviews perstack.toml for instruction quality and signal design.
 Provide: (1) path to perstack.toml, (2) the user's original request.
@@ -216,9 +226,16 @@ You review perstack.toml quality. Read the file, then check each item below. Mar
 
 ## Checklist
 
+### Structural correctness
+- Every expert has: version, defaultModelTier, description, instruction, skills? (✓/✗)
+- defaultModelTier values are exactly "low", "middle", or "high"? (✓/✗)
+- Tool names in pick lists are from the valid set (readTextFile, writeTextFile, editTextFile, exec, todo, attemptCompletion, addDelegateFromConfig, addDelegate, removeDelegate)? (✓/✗)
+- No unknown fields (no instructionFile, defaultSkill, or custom fields)? (✓/✗)
+- Every coordinator has a delegates array? (✓/✗)
+
+### Instruction quality
 For library/tool names in any instruction:
 - Specified by the user in the original request? (✓/✗ per name)
-- If not user-specified, the instruction should describe the capability, not name the tool.
 
 For each non-coordinator instruction, flag (✗) if any of the following appear:
 - Output locations or structure — dictates where to place results or enumerates artifacts
@@ -227,7 +244,7 @@ For each non-coordinator instruction, flag (✗) if any of the following appear:
 - Implementation approach — describes how to build rather than what constraints to satisfy
 - Code snippets, data schemas, or step-by-step procedures
 
-For the embedded test spec:
+### Test spec
 - Must signal: exactly one, checks core task completion? (✓/✗)
 - Should signals: each is a deterministic command with expected result? (✓/✗)
 - Sign-off threshold defined? (✓/✗)
@@ -253,7 +270,7 @@ pick = ["readTextFile", "todo", "attemptCompletion"]
 
 [experts."@create-expert/verify"]
 defaultModelTier = "low"
-version = "1.0.24"
+version = "1.0.25"
 description = """
 Runs the test query via @create-expert/test, then executes hard signal checks from the perstack.toml header.
 Provide: (1) path to perstack.toml, (2) the coordinator expert name to test.
@@ -310,7 +327,7 @@ pick = ["readTextFile", "exec", "todo", "attemptCompletion"]
 
 [experts."@create-expert/test"]
 defaultModelTier = "low"
-version = "1.0.24"
+version = "1.0.25"
 description = """
 Executes a test query against a Perstack expert and reports what happened.
 Provide: (1) path to perstack.toml, (2) the test query, (3) the coordinator expert name.