| name | repo-preflight |
| description | Establish release readiness through layered validation that automatically repairs deterministic inconsistencies in versions, skill counts, and changelogs while surfacing issues requiring human judgment. Use when: (1) before creating any git commit in the thinkies repository, (2) after adding or modifying skills to catch metadata drift, (3) after version bumps to ensure consistency across all files, (4) skill counts in README files or version numbers in metadata files appear inconsistent, (5) as part of continuous integration validation, (6) after bulk operations that touched multiple skills |
Repo Preflight
Establish repository health through progressive validation layers, each building confidence that metadata reflects filesystem reality and that changes won't break existing functionality.
Instructions
1. Synchronize version truth across files. Parse version numbers from plugin.json files alongside their marketplace.json entries to identify drift—when versions diverge, marketplace.json updates to match plugin.json since plugin metadata serves as canonical source, establishing version consistency that prevents installation errors downstream.
2. Align documentation with filesystem reality. Count SKILL.md files within each plugin's skills directory and compare these counts against skill totals claimed in README files—when documentation drifts from reality, update README counts to match actual files so readers encounter accurate information that builds rather than undermines trust in the repository.
3. Ensure changelog infrastructure exists. Verify each plugin directory contains a CHANGELOG.md file tracking version history—when changelogs are missing, create them with initial structure since release management depends on having a place to record changes, and report which infrastructure was added so the gaps are visible.
4. Verify script correctness through tests. Execute the BATS test suite covering all shell scripts to confirm they behave correctly—test failures block commit readiness since broken scripts will create problems for users, and specific failure details surface immediately so the exact issues become actionable without investigation.
5. Synthesize validation results into actionable summary. Consolidate auto-fixes applied, issues requiring manual judgment, and test outcomes into structured report that indicates commit readiness—this synthesis transforms validation details into decision support, making clear whether the repository can proceed or needs attention before committing changes.
Examples
Example: Repository already aligned
Context: All metadata synchronized, no drift detected
Validation sequence:
Versions match across plugin.json and marketplace.json files. Skill counts in READMEs reflect actual SKILL.md file counts. All plugins have CHANGELOG.md files. BATS tests pass.
Output:
Preflight Results
=================
Auto-fixes applied: None
Issues requiring attention: None
Status: ✓ Ready for commit
The clean result confirms metadata integrity without requiring intervention.
Example: Metadata drift after development
Context: Version bumps and skill additions created inconsistencies
Validation sequence:
Versions diverge where thinkies plugin.json shows 1.3.0 but marketplace.json shows 1.2.0—sync marketplace to match. Software README claims 18 skills but filesystem contains 19 SKILL.md files—update README count. Expression plugin lacks CHANGELOG.md—create initial structure.
Output:
Preflight Results
=================
Auto-fixes applied:
✓ Synced thinkies version (1.2.0 → 1.3.0) in marketplace.json
✓ Updated skill count in software README (18 → 19)
✓ Created CHANGELOG.md for expression plugin
Issues requiring attention: None
Status: ✓ Ready for commit
The results show automated repairs restoring consistency across metadata files.
Example: New plugin requires manual integration
Context: Plugin structure exists but marketplace integration missing
Validation sequence:
New plugin has no marketplace.json entry—this requires manual addition since the plugin's category and positioning need human decision. README contains placeholder skill count—update to actual count of zero. CHANGELOG.md missing—create initial structure.
Output:
Preflight Results
=================
Auto-fixes applied:
✓ Updated skill count in newplugin README (TBD → 0)
✓ Created CHANGELOG.md for newplugin
Issues requiring attention:
⚠ Plugin 'newplugin' not found in marketplace.json - needs manual addition
Status: Not ready for commit (requires marketplace.json update)
The blocking status prevents committing incomplete plugin integration while automated fixes handle deterministic setup.
