From 6a48de189d1c18a25b1bfca36ed4ffbb00c08d60 Mon Sep 17 00:00:00 2001 From: HiranoMasaaki Date: Sat, 14 Mar 2026 11:23:34 +0000 Subject: [PATCH] fix: complete write schema reference and add structural checks to review Write was producing invalid tool names (readFile), invalid modelTier (mid), and unknown fields (instructionFile) because the schema didn't specify valid values. Review wasn't catching these because its checklist only covered instruction content quality, not structural correctness. Changes: - write: schema lists valid defaultModelTier values, valid tool names for pick, and allowed fields per expert. Add instruction quality guidance (domain constraints only, no implementation procedures). - review: add structural correctness section to checklist (valid field names, valid tool names, valid modelTier values, required fields). - Bump to 1.0.25. Co-Authored-By: Claude Opus 4.6 (1M context) --- definitions/create-expert/perstack.toml | 43 +++++++++++++++++-------- 1 file changed, 30 insertions(+), 13 deletions(-) diff --git a/definitions/create-expert/perstack.toml b/definitions/create-expert/perstack.toml index d26725aa..3a742c82 100644 --- a/definitions/create-expert/perstack.toml +++ b/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.