[#181] feat: publish to npmjs.org + genericize skills + layout docs

[rucka]

Summary

What Changed

1. npm publish: Switch package distribution from GitHub Packages to npmjs.org with standalone publish script
2. Skills genericization: Manual test skills no longer hardcode pair-specific categories
3. Layout documentation: --layout option documented + new packaging tutorial + CP8 manual tests

Why This Change

• npx @foomakers/pair-cli install failed with E404 (GitHub Packages requires .npmrc + PAT) — Setup & Project Management Integration #1 adoption blocker
• Manual test skills were pair-specific instead of reusable
• --layout source|target was undocumented for pair package

Story Context

User Story: As a developer wanting to use pair, I want to install @foomakers/pair-cli via npx without extra configuration.

Acceptance Criteria: 8/8 covered. T-6 (local publish verification) completed — PUT 200 confirmed.

Changes Made

npm Publish (T-1 → T-5)

• publishConfig.registry → registry.npmjs.org + access: public
• Changeset access restricted → public
• create-registry-tgz.sh patches to npmjs.org at pack time
• New scripts/publish-npm.sh — standalone with metadata validation, fail-fast, --dry-run
• release.yml: publish-gh-packages (133 lines) → publish-npm (22 lines)
• Install docs: @pair/pair-cli → @foomakers/pair-cli (7 website files)
• CP7 rewritten for public npmjs.org (no auth)
• CP3: added MT-CP320 (npx from registry, no prior config)
• Release validation README: removed $REGISTRY, $NPM_TOKEN, read:packages

Skills Genericization

• design-manual-tests: $scope auto-discovered, discovery table generic, CP pattern is example heuristic
• execute-manual-tests: variables resolved from suite README (no hardcoded $REGISTRY)
• Propagated via pair update

Layout Docs + Manual Tests

• --layout added to pair package in commands.mdx
• New guide: guides/packaging.mdx (source vs target layout tutorial)
• CP8: 6 manual tests for pair package (both layouts, metadata, validation)

Files Changed

• Added: scripts/publish-npm.sh, apps/website/content/docs/guides/packaging.mdx, qa/release-validation/CP8-packaging.md
• Modified: apps/pair-cli/package.json, .changeset/config.json, scripts/workflows/release/create-registry-tgz.sh, .github/workflows/release.yml, apps/website/content/docs/reference/cli/commands.mdx, apps/website/content/docs/guides/meta.json, 7 website docs files, qa/release-validation/CP7-registry-publish.md, qa/release-validation/CP3-cli-install-update.md, qa/release-validation/README.md, 2 dataset skill files, installed skill files (via update)

Testing

Test Results

Quality Gate: PASS (ts:check, test, lint, prettier, mdlint)
Website Build: PASS
Docs Staleness: PASS (33 skills, 8 commands in sync)
npm Publish: VERIFIED — @foomakers/pair-cli@0.4.2 live on npmjs.org

Testing Strategy

• Automated: Quality gate, website build, docs staleness check
• Manual (T-6): scripts/publish-npm.sh executed locally — PUT 200 to registry.npmjs.org confirmed
• **npx @foomakers/pair-cli install: PASS (zero config, clean machine)

Reviewer Guide

Review Focus Areas

1. scripts/publish-npm.sh — error handling, auth flow, fail-fast
2. release.yml — publish-npm job trigger conditions
3. Dataset skills — verify genericization (no pair-specific categories)
4. guides/packaging.mdx — source vs target layout accuracy
5. Docs — no remaining @pair/pair-cli in user-facing install commands

Testing the Changes

git checkout 'feature/#181-publish-npmjs'
pnpm install && pnpm quality-gate

# Verify publish script
./scripts/publish-npm.sh --help

# Verify no GitHub Packages refs
grep -r "npm.pkg.github.com" . --include="*.json" --include="*.yml" --include="*.sh"

# Verify generic skills
grep "Website Critical Path\|CLI Artifact" packages/knowledge-hub/dataset/.skills/capability/design-manual-tests/SKILL.md
# Should show as example, not fixed table

Closes #181

[rucka]

Code Review — PR #190

Decision: CHANGES REQUESTED (posted as COMMENT — can't request changes on own PR)

Review Information

PR: #190 — [#181] feat: publish to npmjs.org + genericize skills + layout docs
Author: rucka
Reviewer: AI pair (Claude Code)
Date: 2026-04-11
Story: #181 — Publish @foomakers/pair-cli to npmjs.org
Review Type: Feature
Files Changed: 25 files, +577/−275 lines

Review Summary

Overall Assessment: REQUEST CHANGES

Core implementation is solid — publish script, release.yml rewrite, docs updates, skill genericization, and new CP7/CP8/packaging guide are well done. However, leftover npm.pkg.github.com references in 4 files outside the PR scope contradict AC-5 and the DoD. Stale comments in create-registry-tgz.sh are misleading.

Key Changes

1. npm publish: GitHub Packages → npmjs.org with standalone publish-npm.sh
2. Skills genericization: Dynamic category discovery replaces hardcoded pair-specific categories
3. Layout docs: --layout option documented, new guides/packaging.mdx, CP8 manual tests

Business Value

Removes the #1 adoption blocker: npx @foomakers/pair-cli install now works without .npmrc or PAT setup.

Quality Gates

Quality Gate:     PASS (ts:check, test, lint, prettier, mdlint — all cached)
Hygiene Check:    PASS — no violations
Docs Staleness:   PASS — 33 skills, 8 commands in sync

Code Review Checklist

Functionality Review

• Requirements Met — 7/8 AC fully met, AC-5 partially met
• Business Logic — Publish flow is correct: TGZ → validate → publish → verify
• Integration — release.yml, publish script, create-registry-tgz.sh work as pipeline
• Error Handling — publish-npm.sh has fail-fast, scope validation, dual auth, actionable errors

Code Quality

• Readability — Scripts are well-commented and structured
• Naming — Clear (publish-npm.sh, CP7-registry-publish.md, packaging.mdx)
• Comments — create-registry-tgz.sh:96-97 comments say "GitHub Packages" but code targets npmjs.org

Technical Standards

• Architecture — No new patterns or libraries
• Dependencies — No new deps added
• Consistency — Leftover npm.pkg.github.com refs in 4 non-PR files

Security Review

• Secrets Management — NPM_TOKEN via env var (CI) or npm login session (local). No hardcoded tokens.
• Scope Validation — Script validates package is scoped to @foomakers/*
• Access Control — --access public is explicit and intentional for npmjs.org

Testing Review

Quality Gate:       PASS (all gates)
Manual Publish:     VERIFIED (PUT 200 to npmjs.org)
npx Install:        VERIFIED (clean machine, no .npmrc)
CP7/CP8 Execution:  Not yet executed (post-merge validation)

AC Coverage

AC	Status	Notes
AC-1 (npx works, no config)	✅	T-1, T-2, T-6 — author verified
AC-2 (npm install works)	✅	T-1, T-2, T-6
AC-3 (publish script local)	✅	PUT 200 confirmed
AC-4 (release.yml tag/dispatch)	✅	Verified in workflow
AC-5 (no GitHub Packages refs)	⚠️ PARTIAL	Workflow clean, but 4 other files still have refs
AC-6 (docs updated)	✅	7 website files + README
AC-7 (CP7 rewritten)	✅	npmjs.org, P0, no auth
AC-8 (CP3 + MT-CP320)	✅	Verified in CP3:459

Detailed Review Comments

Positive Feedback ✅

• scripts/publish-npm.sh — well-structured: fail-fast, clear errors, scope validation, dual auth
• release.yml publish job: 133 lines → 22 lines — excellent simplification
• Skill genericization is a real improvement — dynamic discovery replaces hardcoded categories
• guides/packaging.mdx is thorough and well-organized
• CP7 rewrite is clean: P0, no auth, clear preconditions
• CP8 covers both layout modes with good test progression

Major Issues 🔍 (must fix)

1. Stale npm.pkg.github.com references (AC-5 / DoD gap)

Story DoD: "No references to npm.pkg.github.com remain in codebase." These were missed:

File	Line	Content
qa/release-validation/CP2-cli-artifact-critical-path.md	207	publishConfig.registry == https://npm.pkg.github.com/
RELEASE.md	129-130, 139	.npmrc setup for GitHub Packages
apps/website/content/docs/tutorials/enterprise-adoption.mdx	227	@your-org:registry=https://npm.pkg.github.com
DEVELOPMENT.md	199	@foomakers:registry=https://npm.pkg.github.com/

Fix: Update all 4 files to replace GitHub Packages refs with npmjs.org equivalents.

---

2. Stale comments in create-registry-tgz.sh:96-97

# Ensure the package.json inside the extracted artifact is scoped for GitHub Packages
echo "Patching package.json for GitHub Packages registry and setting package name/version..."

Code patches to registry.npmjs.org. Comments are misleading.

Fix: s/GitHub Packages/npmjs.org/ in both lines.

Minor Issues 💡 (consider fixing)

3. scripts/diagnose-install.sh:154-166,248-249 — checks for @pair/pair-cli in global installs. Published name is @foomakers/pair-cli.

4. publish-npm.sh:84 — $DRY_RUN unquoted (shellcheck SC2086). Not a bug but inconsistent with quoting elsewhere.

5. create-registry-tgz.sh:108 — o.private = !!o.private ? o.private : false; preserves private: true. If preparing for publish, o.private = false is more explicit.

Questions ❓

6. release.yml publish-npm job if: checks workflow_dispatch+publish=true and push+tags/v*, but not release: [published]. If a GitHub Release is created from an existing tag (no new push), publish-npm won't run. Intentional?

Risk Assessment

Risk	Impact	Probability	Mitigation
Stale CP2 expects wrong registry	False test failure next release	Medium	Fix CP2:207
diagnose-install.sh wrong scope	Users get "not installed" for working install	Low	Update to @foomakers/pair-cli

Tech Debt

• ADL candidate: GitHub Packages → npmjs.org is an infrastructure decision worth recording.

DoD Assessment: 14/16

• ⚠️ "No npm.pkg.github.com references remain" — PARTIAL (4 files missed)
• ⏳ "Code reviewed and merged" — in progress

---

REVIEW COMPLETE:
├── PR:         #190 — publish to npmjs.org + genericize skills + layout docs
├── Story:      #181 — Publish @foomakers/pair-cli to npmjs.org
├── Decision:   CHANGES-REQUESTED
├── Issues:     critical: 0 | major: 2 | minor: 3
├── Quality:    PASS — all gates
├── DoD:        14/16 criteria met
├── Adoption:   No new deps, no stack changes
├── Debt:       1 item (ADL for registry switch)
└── Report:     Posted as PR review comment

[rucka]

Review Issues — Resolved

All issues from the code review have been fixed in the working tree. Summary:

Major Issues (fixed)

#	Issue	File(s)	Fix Applied
1	Stale npm.pkg.github.com ref	CP2:207	→ https://registry.npmjs.org/
2	Stale GitHub Packages section	RELEASE.md:117-148	Rewrote to npmjs.org (NPM_TOKEN, no .npmrc for consumers)
3	Stale GitHub Packages callout	enterprise-adoption.mdx:224-230	Rewrote for public npmjs.org packages
4	Stale GitHub Packages section	DEVELOPMENT.md:192-204	Rewrote to npmjs.org
5	Stale comments	create-registry-tgz.sh:96-97	"GitHub Packages" → "npmjs.org"

Minor Issues (fixed)

#	Issue	File(s)	Fix Applied
6	Wrong @pair/pair-cli scope	diagnose-install.sh:154,155,165,166,248,249	→ @foomakers/pair-cli
7	Unquoted $DRY_RUN	publish-npm.sh:84	→ ${DRY_RUN:+"$DRY_RUN"}
8	Confusing private logic	create-registry-tgz.sh:108	!!o.private ? o.private : false → false

Verification

grep npm.pkg.github.com:  0 matches (was 6)
Quality Gate:              PASS
Hygiene Check:             PASS
Docs Staleness:            PASS — 33 skills, 8 commands in sync

Review Question #6 (dropped)

release.yml publish-npm doesn't handle release: [published] event

Not a new issue — the old publish-gh-packages job had the same if: pattern. Tag push covers the release event flow. Dropped.