---

name: npm-monorepo-publish description: Publish packages to npm using release branch workflow with PR review before publishing version: 2.1.0

npm Monorepo Publishing Skill

Purpose

Guide the publishing of packages to npm using a release branch workflow that ensures:

• All publishes reviewed via PR before going live
• Build/test validation before creating release branch
• Main branch never force-pushed (fix forward only)
• Full audit trail with every publish linked to a PR

Core principle: Never publish directly from main. Always use release branches.

Scope: Works with any package in the monorepo (currently: @fpkit/acss, expandable to other packages)

---

When to Invoke

User requests:

• "Publish to npm"
• "Release a new version"
• "Create a patch/minor/major release"
• "Publish the package"

Arguments:

• --dry-run - Validate without publishing

First step: If multiple packages exist or context is unclear, ask user which package to publish.

---

Project Context

Key configuration:

• Versioning: Independent (Lerna manages per-package)
• Conventional commits: Enabled (auto-changelog)
• Requirements: Node >=22.12.0, npm >=8.0.0

Current packages:

• @fpkit/acss in packages/fpkit/

---

Workflow Overview

8-Step Release Branch Flow:

For detailed instructions: See references/detailed-workflow.md

---

Quick Reference

Experienced users - full command sequence:

Copy# Validate → Branch → Version → PR → Publish

git checkout main && git status
cd packages/fpkit && npm run build && npm run lint && npm test && cd ../..
git checkout -b release/v{VERSION}
lerna version {patch|minor|major} --no-push --no-git-tag-version
# Update CHANGELOG, commit
git push -u origin release/v{VERSION}
gh pr create --title "chore(release): publish @fpkit/acss@{VERSION}" --body "..."
# After PR merge:
git checkout main && git pull
lerna publish from-package --yes --otp={6-digit-code}
git push --follow-tags
git branch -d release/v{VERSION} && git push origin --delete release/v{VERSION}

---

Common Mistakes to Avoid

---

Safety Checks

Pre-publish Blockers

Abort if any of these fail:

Major Version Protection

If major version detected (X.0.0 → X+1.0.0):

Copy⚠️ BREAKING CHANGE - Major version bump

Requires before proceeding:
- MIGRATION.md guide created
- CHANGELOG lists all breaking changes
- Documentation updated

Confirm: "yes, publish major version"

Wait for exact confirmation phrase. If not confirmed: Abort.

---

Dry-Run Mode

Flag: --dry-run

Use case: Test workflow before real publish, especially from feature branches

---

Recovery Decision Tree

CopyWas package published to npm?
│
├─ NO → Was PR merged?
│        ├─ NO → Delete branch, fix issues, restart
│        └─ YES → Fix forward on main, new release PR
│
└─ YES → Publish corrective patch via new PR
         (Cannot unpublish from npm)

For detailed recovery scenarios: See references/rollback-recovery.md

Quick recovery guide:

---

Tool Usage Guide

Use these tools in order of preference:

Never use:

• Write - Lerna handles file updates automatically
• Edit - Version bumps managed by Lerna

Parallel execution:

• ✅ Pre-flight checks (Step 1): Run in parallel
• ❌ Build/lint/test (Step 3): Run sequentially
• ✅ Post-publish verification: Run in parallel

---

Key Files

This skill reads:

• lerna.json - Lerna configuration
• packages/fpkit/package.json - Package metadata
• CHANGELOG.md - Release history
• .git/ - Branch, tags, commits

This skill modifies:

• packages/fpkit/package.json - Version field (Step 5)
• CHANGELOG.md - Release notes (Step 6)
• Git branches, tags (Steps 4, 8)

This skill publishes to:

• npm registry: https://www.npmjs.com/package/@fpkit/acss

---

Version Validation Steps

---

OTP Authentication

Format: Exactly 6 numeric digits

Best practices:

• Generate OTP immediately before publishing
• Don't wait >20 seconds before using code
• Keep authenticator app ready
• If expired, request fresh code (don't retry same)

See: references/technical-reference.md for OTP debugging

---

Helper Scripts

Recommendation: Use interactive script for full automation and built-in error handling

---

Support & Resources

Common issues:

External resources:

• npm package: https://www.npmjs.com/package/@fpkit/acss
• GitHub repo: https://github.com/shawn-sandy/fpkit
• Lerna docs: https://lerna.js.org/
• npm status: https://status.npmjs.org/

Reference files:

• references/detailed-workflow.md - Step-by-step instructions for each workflow step
• references/rollback-recovery.md - Recovery scenarios and fix-forward strategies
• references/technical-reference.md - OTP, Lerna behavior, environment variables
• references/workflow-examples.md - Real-world publish examples
• references/troubleshooting.md - Error messages and solutions

---

END OF SKILL