Project Standardization & Automation for @j0kz/mcp-agents
Ensure consistency across monorepo using automated scripts and established patterns.
4 Critical Rules (NEVER VIOLATE)
Rule 1: version.json is Single Source of Truth
-
❌ NEVER manually edit package.json versions
-
✅ ALWAYS use: npm run version:sync
-
11 packages must stay in sync
Rule 2: URL Casing Rules
-
GitHub: j0KZ (capital K, Z)
-
npm: @j0kz (lowercase)
-
Mixing breaks links and installations
Rule 3: Test Count Automation
-
❌ NEVER manually edit test badges
-
✅ ALWAYS use: npm run update:test-count
-
Currently: 632 tests passing
Rule 4: @latest in Documentation
-
❌ WRONG: npx @j0kz/mcp-agents@1.0.36
-
✅ RIGHT: npx @j0kz/mcp-agents@latest
Quick Command Reference
Version management
npm run version:sync # Sync all versions from version.json npm run version:check-shared # Verify shared package versions
Testing
npm test # Run all tests npm run update:test-count # Update test count in docs
Building
npm run build # Build all packages npm run dev # Watch mode
Publishing
npm run publish-all # Publish all packages
Version Management Workflow
Quick Start: New Release
1. Update version.json
echo '{"version": "1.1.0"}' > version.json
2. Sync and build
npm run version:sync npm run version:check-shared npm test npm run build
3. Publish
npm run publish-all cd installer && npm publish && cd ..
4. Git operations
git add . && git commit -m "release: v1.1.0" git tag v1.1.0 && git push origin main --tags
For detailed release workflow with all steps:
cat .claude/skills/project-standardization/references/version-management-guide.md
Test Count Management
After adding/removing tests
npm run update:test-count
Updates 3 files automatically:
- README.md badge
- wiki/Home.md badge and table
- CHANGELOG.md metrics
For test automation details and patterns:
cat .claude/skills/project-standardization/references/test-automation-guide.md
URL & Link Standards
Critical: GitHub uses j0KZ , npm uses @j0kz
For complete URL standards and examples:
cat .claude/skills/project-standardization/references/url-standards-guide.md
tools.json Management
Location: tools.json at repository root - Single source of truth for all MCP tool metadata
When to update:
-
Adding new MCP tool
-
Changing tool features/descriptions
-
Adding new category
Structure includes: tool id, name, package, description, category, features, wikiPage
Workspace Management
Adding New Package
mkdir packages/new-tool npm install # Auto-discovers workspace npm ls --workspaces # Verify recognized
Dependency Installation
npm install typescript -w packages/new-tool # Specific workspace npm install typescript --workspaces # All workspaces npm install vitest -D # Root only
Common Mistakes and Quick Fixes
Mistake Fix
Manually edited package.json version npm run version:sync
Hardcoded version instead of @latest Use @latest in docs
Wrong URL casing (GitHub/npm) GitHub: j0KZ , npm: @j0kz
Manually updated test count npm run update:test-count
Forgot to sync after version.json change Always run version:sync first
Validation & Checklists
For complete validation checklists (pre-commit, pre-publish, post-publish):
cat .claude/skills/project-standardization/references/validation-checklists.md
Key File Locations
version.json # Single source of truth for versions tools.json # MCP tool metadata scripts/sync-versions.js # Version sync automation scripts/update-test-count.js # Test count automation scripts/enforce-shared-version.js # Shared version validation
Getting Help
Check current state
cat version.json # Current version npm run version:check-shared # Package consistency git status # Uncommitted changes
Review scripts
ls scripts/ # List all automation cat scripts/sync-versions.js # Read script details
Related Skills
-
monorepo-package-workflow: Creating new MCP packages
-
release-publishing-workflow: Complete release process
-
git-pr-workflow: Git operations and PR creation
Additional Resources
-
CLAUDE.md: Repository-wide standards and patterns