Skip to content

Docs: document Perstack Properties (PS-XXX) framework or internalize as create-expert-only concept #379

@FL4TLiN3

Description

@FL4TLiN3

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:

  1. Do One Thing Well
  2. Trust the LLM, Define Domain Knowledge
  3. Let Them Collaborate
  4. Keep It Verifiable
  5. Ship Early

Questions to Resolve

  1. 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
  2. How do PS-XXX properties map to the Five Principles?

Affected Areas

  • apps/create-expert/src/lib/create-expert-toml.ts
  • apps/create-expert/src/lib/agents-md-template.ts
  • docs/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

Metadata

Metadata

Assignees

No one assigned

    Labels

    create-expertcreate-expert CLI packagedocsDocumentation only

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions