From 8dd16a17c81d9cb29c95f6a71b4aca8a68cbb7b5 Mon Sep 17 00:00:00 2001 From: HiranoMasaaki Date: Sat, 3 Jan 2026 07:29:15 +0000 Subject: [PATCH 1/2] docs(create-expert): internalize PS-XXX properties as framework-specific MIME-Version: 1.0 Content-Type: text/plain; charset=UTF-8 Content-Transfer-Encoding: 8bit Rename "Perstack Properties (PS-XXX format)" to "Framework Quality Properties (create-expert internal)" to clarify these are internal to the create-expert framework, not official Perstack public concepts. Changes: - Remove PS-XXX identifiers (PS-SEC-01, PS-DESIGN-01, etc.) - Rename to "Framework Quality Properties" - Add note referencing docs/making-experts/best-practices.md for public guidelines - Update both create-expert-toml.ts and agents-md-template.ts This avoids confusion with the public "Five Principles" documented in docs/making-experts/best-practices.md. Closes #379 🤖 Generated with [Claude Code](https://claude.com/claude-code) Co-Authored-By: Claude Opus 4.5 --- .../src/lib/agents-md-template.ts | 21 +++++++++++-------- .../src/lib/create-expert-toml.ts | 21 +++++++++++-------- 2 files changed, 24 insertions(+), 18 deletions(-) diff --git a/apps/create-expert/src/lib/agents-md-template.ts b/apps/create-expert/src/lib/agents-md-template.ts index 50e3ebeb..51dfb03a 100644 --- a/apps/create-expert/src/lib/agents-md-template.ts +++ b/apps/create-expert/src/lib/agents-md-template.ts @@ -61,21 +61,24 @@ create-expert (Coordinator) - Expected inputs and outputs - Domain-specific behaviors -**Perstack Properties** (always verified): +**Framework Quality Properties** (create-expert internal, always verified): + +These ensure experts follow Perstack best practices. +See docs/making-experts/best-practices.md for public guidelines. *Security:* -- PS-SEC-01: Minimal tool access - uses \`pick\` for only needed tools -- PS-SEC-02: Minimal environment - uses \`requiredEnv\` for only needed variables -- PS-SEC-03: Maintains boundaries - protects internal information +- Minimal tool access: Uses \`pick\` for only needed tools +- Minimal environment: Uses \`requiredEnv\` for only needed variables +- Maintains boundaries: Protects internal information *Design:* -- PS-DESIGN-01: Single responsibility - does one thing well -- PS-INST-01: Declarative instructions - policies not procedures -- PS-INST-02: Contains domain knowledge +- Single responsibility: Does one thing well +- Declarative instructions: Policies not procedures +- Contains domain knowledge: Expertise embedded in instruction *Output:* -- PS-OUT-01: Uses \`attemptCompletion\` for final output -- PS-OUT-02: Error handling - graceful with helpful messages +- Uses \`attemptCompletion\`: Signals completion properly +- Error handling: Graceful with helpful messages ## CLI Reference diff --git a/apps/create-expert/src/lib/create-expert-toml.ts b/apps/create-expert/src/lib/create-expert-toml.ts index d77fc651..9ff37cf5 100644 --- a/apps/create-expert/src/lib/create-expert-toml.ts +++ b/apps/create-expert/src/lib/create-expert-toml.ts @@ -56,21 +56,24 @@ Return a structured list of properties: ### User Properties (from requirements) 1. [Property name]: [Description] - [Success criteria] -### Perstack Properties (PS-XXX format) +### Framework Quality Properties (create-expert internal) + +These properties ensure experts follow Perstack best practices. +See docs/making-experts/best-practices.md for the public guidelines. **Security:** -- PS-SEC-01: Minimal tool access - uses \`pick\` for only needed tools -- PS-SEC-02: Minimal environment - uses \`requiredEnv\` for only needed variables -- PS-SEC-03: Maintains boundaries - protects internal information +- Minimal tool access: Uses \`pick\` for only needed tools +- Minimal environment: Uses \`requiredEnv\` for only needed variables +- Maintains boundaries: Protects internal information **Design:** -- PS-DESIGN-01: Single responsibility - does one thing well -- PS-INST-01: Declarative instructions - policies not procedures -- PS-INST-02: Contains domain knowledge +- Single responsibility: Does one thing well +- Declarative instructions: Policies not procedures +- Contains domain knowledge: Expertise embedded in instruction **Output:** -- PS-OUT-01: Uses \`attemptCompletion\` for final output -- PS-OUT-02: Error handling - graceful with helpful messages +- Uses \`attemptCompletion\`: Signals completion properly +- Error handling: Graceful with helpful messages ### Usability Properties (always verified) 1. Zero-Config: Demo mode works without any setup OR setup is fully automated From 9176a40f34b8147782aee7d5859249261e71e59f Mon Sep 17 00:00:00 2001 From: HiranoMasaaki Date: Sat, 3 Jan 2026 07:39:40 +0000 Subject: [PATCH 2/2] chore: add changeset for #379 --- .changeset/docs-379-ps-xxx-properties.md | 5 +++++ 1 file changed, 5 insertions(+) create mode 100644 .changeset/docs-379-ps-xxx-properties.md diff --git a/.changeset/docs-379-ps-xxx-properties.md b/.changeset/docs-379-ps-xxx-properties.md new file mode 100644 index 00000000..d13ad1ee --- /dev/null +++ b/.changeset/docs-379-ps-xxx-properties.md @@ -0,0 +1,5 @@ +--- +"create-expert": patch +--- + +Internalize PS-XXX properties as framework-specific