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.