-
Notifications
You must be signed in to change notification settings - Fork 1
Closed
Labels
create-expertcreate-expert CLI packagecreate-expert CLI packagedocsDocumentation onlyDocumentation only
Description
Description
The create-expert framework defines "Perstack Properties" with PS-XXX identifiers, but these are not documented in the public documentation. This creates confusion about whether these are official Perstack concepts or internal implementation details.
Current State
In apps/create-expert/src/lib/create-expert-toml.ts:
### Perstack Properties (PS-XXX format)
**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
**Design:**
- PS-DESIGN-01: Single responsibility - does one thing well
- PS-INST-01: Declarative instructions - policies not procedures
- PS-INST-02: Contains domain knowledge
**Output:**
- PS-OUT-01: Uses `attemptCompletion` for final output
- PS-OUT-02: Error handling - graceful with helpful messages
Also in apps/create-expert/src/lib/agents-md-template.ts (AGENTS.md template).
However, docs/making-experts/best-practices.md does not mention these identifiers. The "Five Principles" in docs are:
- Do One Thing Well
- Trust the LLM, Define Domain Knowledge
- Let Them Collaborate
- Keep It Verifiable
- Ship Early
Questions to Resolve
-
Are PS-XXX properties meant to be public Perstack standards?
- If yes: Document them in
docs/making-experts/best-practices.md - If no: Rename to avoid confusion with official Perstack concepts
- If yes: Document them in
-
How do PS-XXX properties map to the Five Principles?
- PS-DESIGN-01 ≈ Principle Docs: Add related documentation links to runtime README #1 (Do One Thing Well)
- PS-INST-01, PS-INST-02 ≈ Principle chore: version packages #2 (Trust the LLM)
- Others don't have clear mappings
Affected Areas
apps/create-expert/src/lib/create-expert-toml.tsapps/create-expert/src/lib/agents-md-template.tsdocs/making-experts/best-practices.md(if documenting)
Acceptance Criteria
Option A: Document PS-XXX publicly
- Add PS-XXX properties to
docs/making-experts/best-practices.md - Explain relationship to Five Principles
- Add reference in creating-expert workflow
Option B: Internalize as create-expert-only
- Rename to avoid "Perstack Properties" terminology
- Clarify in AGENTS.md that these are framework-specific
- Keep docs/best-practices.md as the public standard
Reactions are currently unavailable
Metadata
Metadata
Assignees
Labels
create-expertcreate-expert CLI packagecreate-expert CLI packagedocsDocumentation onlyDocumentation only