Skip to content

refactor(create-expert): consolidate duplicate property definitions with sync notes#395

Merged
FL4TLiN3 merged 2 commits intomainfrom
refactor/385-consolidate-duplicates
Jan 3, 2026
Merged

refactor(create-expert): consolidate duplicate property definitions with sync notes#395
FL4TLiN3 merged 2 commits intomainfrom
refactor/385-consolidate-duplicates

Conversation

@FL4TLiN3
Copy link
Contributor

@FL4TLiN3 FL4TLiN3 commented Jan 3, 2026

Summary

Adds synchronization notes between create-expert-toml.ts and agents-md-template.ts for the Framework Quality Properties that are defined in both files.

Changes

  1. Renamed "Perstack Properties" to "Framework Quality Properties"

  2. Removed PS-XXX identifiers

  3. Added synchronization notes

    • Both files now include: "Note: Also defined in [other file] - keep synchronized"
    • Makes duplication explicit and prevents drift
  4. Added documentation references

    • Both files reference docs/making-experts/best-practices.md for public guidelines

Why Not Full Consolidation

Full consolidation (extracting to a shared module) would require refactoring the template string structure significantly. The synchronization notes approach:

  • Makes duplication explicit
  • Prevents accidental drift
  • Low-risk change
  • Can be improved later if needed

Closes #385

Test plan

  • CI passes
  • No behavior changes expected

Note

Clarifies duplication of Framework Quality Properties and reduces drift risk by adding explicit sync notes.

  • Adds cross-references in agents-md-template.ts and create-expert-toml.ts noting the properties are defined in both files and must be kept synchronized
  • Introduces a changeset for a patch release

Written by Cursor Bugbot for commit 1fa212e. This will update automatically on new commits. Configure here.

@codecov
Copy link

codecov bot commented Jan 3, 2026

Codecov Report

✅ All modified and coverable lines are covered by tests.

📢 Thoughts on this report? Let us know!

FL4TLiN3 and others added 2 commits January 3, 2026 07:54
…ith sync notes

Add synchronization notes between create-expert-toml.ts and agents-md-template.ts
for the Framework Quality Properties that are defined in both files.

Changes:
- Rename "Perstack Properties" to "Framework Quality Properties" (consistency)
- Remove PS-XXX identifiers (consistency with #379)
- Add "Note: Also defined in [other file] - keep synchronized" to both files
- Reference docs/making-experts/best-practices.md for public guidelines

While full consolidation (extracting to shared module) would require refactoring
the template string structure, adding synchronization notes prevents drift and
makes the duplication explicit.

Closes #385

🤖 Generated with [Claude Code](https://claude.com/claude-code)

Co-Authored-By: Claude Opus 4.5 <noreply@anthropic.com>
@FL4TLiN3 FL4TLiN3 force-pushed the refactor/385-consolidate-duplicates branch from 4bedbc9 to 1fa212e Compare January 3, 2026 07:54
- Error handling: Graceful with helpful messages

Note: These properties are also defined in create-expert-toml.ts.
Keep both files synchronized when updating.
Copy link

Choose a reason for hiding this comment

The reason will be displayed to describe this comment to others. Learn more.

Internal sync notes leak into generated output

The synchronization notes are placed inside template strings rather than as code comments. In agents-md-template.ts, the note referencing create-expert-toml.ts will appear in every generated AGENTS.md file that users see. In create-expert-toml.ts, the note referencing agents-md-template.ts becomes part of the PROPERTY_EXTRACTOR_INSTRUCTION sent to the LLM. These internal developer notes reference source files that end users and LLMs don't have access to, creating confusing output.

Additional Locations (1)

Fix in Cursor Fix in Web

@FL4TLiN3 FL4TLiN3 merged commit 6f854ae into main Jan 3, 2026
7 checks passed
@FL4TLiN3 FL4TLiN3 deleted the refactor/385-consolidate-duplicates branch January 3, 2026 07:58
Sign up for free to join this conversation on GitHub. Already have an account? Sign in to comment

Labels

None yet

Projects

None yet

Development

Successfully merging this pull request may close these issues.

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

1 participant