Skip to content

Refactor: consolidate duplicate PBT framework content between create-expert-toml.ts and agents-md-template.ts #385

@FL4TLiN3

Description

@FL4TLiN3

Description

PBT (Property-Based Testing) framework documentation is duplicated between two files, creating maintenance burden and risk of inconsistency.

Current State

apps/create-expert/src/lib/agents-md-template.ts contains:

  • Framework Architecture diagram
  • Three Testing Stages table
  • Property Categories (User Properties, Perstack Properties)
  • PS-XXX property definitions

apps/create-expert/src/lib/create-expert-toml.ts contains:

  • Same Perstack Properties in PROPERTY_EXTRACTOR_INSTRUCTION
  • Framework delegation structure in expert instructions

Both files define the same concepts in slightly different ways:

agents-md-template.ts:

### Perstack Properties (always verified):

*Security:*
- PS-SEC-01: Minimal tool access - uses `pick` for only needed tools

create-expert-toml.ts (property-extractor):

### Perstack Properties (PS-XXX format)

**Security:**
- PS-SEC-01: Minimal tool access - uses `pick` for only needed tools

Minor formatting differences but same content. If one is updated, the other must be manually synchronized.

Target State

Option A: Single source of truth
Define properties once and import:

// apps/create-expert/src/lib/pbt-properties.ts
export const PERSTACK_PROPERTIES = {
  security: [
    { id: 'PS-SEC-01', name: 'Minimal tool access', ... },
    ...
  ],
  ...
}

export function formatForInstruction(props): string { ... }
export function formatForAgentsMd(props): string { ... }

Option B: Accept duplication but document
Add comment noting both files must be synchronized:

// NOTE: Perstack Properties are also defined in agents-md-template.ts
// Keep both files synchronized when updating

Option C: Remove from one location

  • Keep detailed version in agents-md-template.ts (AGENTS.md is the reference doc)
  • Simplify in property-extractor instruction to just reference the framework

Affected Areas

  • apps/create-expert/src/lib/create-expert-toml.ts
  • apps/create-expert/src/lib/agents-md-template.ts

Acceptance Criteria

  • Single source of truth for property definitions
  • Changes in one place automatically propagate
  • Or: explicit synchronization documentation if keeping duplicates

Metadata

Metadata

Assignees

No one assigned

    Labels

    create-expertcreate-expert CLI packagerefactorCode improvement without behavior change

    Type

    No type

    Projects

    No projects

    Milestone

    No milestone

    Relationships

    None yet

    Development

    No branches or pull requests

    Issue actions